Added some comments concerning stack allocation and references

libuavcan/include/uavcan/node/generic_subscriber.hpp

@@ -140,7 +140,10 @@ public:
     typedef TransferListenerTemplate<BufferSize, NumStaticBufs, NumStaticReceivers> Type;
 };
 
-
+/**
+ * Please note that the reference passed to the RX callback points to a stack-allocated object, which means
+ * that it gets invalidated shortly after the callback returns.
+ */
 template <typename DataSpec, typename DataStruct, typename TransferListenerType>
 class UAVCAN_EXPORT GenericSubscriber : public GenericSubscriberBase
 {

libuavcan/include/uavcan/node/service_client.hpp

@@ -93,6 +93,9 @@ public:
 
     ServiceCallID getCallID() const { return call_id_; }
 
+    /**
+     * Returned reference points to a stack-allocated object.
+     */
     const ResponseFieldType& getResponse() const { return response_; }
     ResponseFieldType& getResponse() { return response_; }
 };
@@ -201,6 +204,10 @@ public:
  * This class can manage multiple concurrent calls to the same or different remote servers. Number of concurrent
  * calls is limited only by amount of available pool memory.
  *
+ * Note that the reference passed to the callback points to a stack-allocated object, which means that the
+ * reference invalidates once the callback returns. If you want to use this object after the callback execution,
+ * you need to copy it somewhere.
+ *
  * @tparam DataType_        Service data type.
  *
  * @tparam Callback_        Service response will be delivered through the callback of this type.

libuavcan/include/uavcan/node/service_server.hpp

@@ -64,6 +64,9 @@ public:
 /**
  * Use this class to implement UAVCAN service servers.
  *
+ * Note that the references passed to the callback may point to stack-allocated objects, which means that the
+ * references get invalidated once the callback returns.
+ *
  * @tparam DataType_        Service data type.
  *
  * @tparam Callback_        Service calls will be delivered through the callback of this type, and service