libuavcan docs

libuavcan_drivers/linux/include/uavcan_linux/helpers.hpp

@@ -15,7 +15,8 @@
 namespace uavcan_linux
 {
 /**
- * Default log sink will dump everything into stderr
+ * Default log sink will dump everything into stderr.
+ * It is installed by default.
  */
 class DefaultLogSink : public uavcan::ILogSink
 {
@@ -29,7 +30,7 @@ class DefaultLogSink : public uavcan::ILogSink
 
 /**
  * Wrapper over uavcan::ServiceClient<> for blocking calls.
- * Calls spin() internally.
+ * Blocks on uavcan::Node::spin() internally until the call is complete.
  */
 template <typename DataType>
 class BlockingServiceClient : public uavcan::ServiceClient<DataType>
@@ -60,6 +61,11 @@ public:
         setup();
     }
 
+    /**
+     * Performs a blocking service call using default timeout (see the specs).
+     * Use @ref getResponse() to get the actual response.
+     * Returns negative error code.
+     */
     int blockingCall(uavcan::NodeID server_node_id, const typename DataType::Request& request)
     {
         const auto SpinDuration = uavcan::MonotonicDuration::fromMSec(2);
@@ -79,6 +85,11 @@ public:
         return call_res;
     }
 
+    /**
+     * Performs a blocking service call using the specified timeout. Please consider using default timeout instead.
+     * Use @ref getResponse() to get the actual response.
+     * Returns negative error code.
+     */
     int blockingCall(uavcan::NodeID server_node_id, const typename DataType::Request& request,
                      uavcan::MonotonicDuration timeout)
     {
@@ -86,8 +97,15 @@ public:
         return blockingCall(server_node_id, request);
     }
 
+    /**
+     * Whether the last blocking call was successful.
+     */
     bool wasSuccessful() const { return call_was_successful_; }
 
+    /**
+     * Use this to retrieve the response on the last blocking service call.
+     * This method returns default constructed response object if the last service call was unsuccessful.
+     */
     const typename DataType::Response& getResponse() const { return response_; }
 };
 
@@ -109,10 +127,11 @@ typedef std::shared_ptr<DriverPack> DriverPackPtr;
 
 typedef std::shared_ptr<uavcan::Timer> TimerPtr;
 
-static constexpr std::size_t NodeMemPoolSize = 1024 * 512;  // One size fits all
+static constexpr std::size_t NodeMemPoolSize = 1024 * 512;  ///< This shall be enough for any possible use case
 
 /**
  * Wrapper for uavcan::Node with some additional convenience functions.
+ * Note that this wrapper adds stderr log sink to @ref uavcan::Logger, which can be removed if needed.
  */
 class Node : public uavcan::Node<NodeMemPoolSize>
 {
@@ -137,7 +156,7 @@ class Node : public uavcan::Node<NodeMemPoolSize>
 
 public:
     /**
-     * Simple forwarding constructor, compatible with uavcan::Node
+     * Simple forwarding constructor, compatible with uavcan::Node.
      */
     Node(uavcan::ICanDriver& can_driver, uavcan::ISystemClock& clock)
         : uavcan::Node<NodeMemPoolSize>(can_driver, clock)
@@ -146,7 +165,7 @@ public:
     }
 
     /**
-     * Takes ownership of the driver container.
+     * Takes ownership of the driver container via the shared pointer.
      */
     explicit Node(DriverPackPtr driver_pack)
         : uavcan::Node<NodeMemPoolSize>(driver_pack->can, driver_pack->clock)
@@ -155,6 +174,11 @@ public:
         getLogger().setExternalSink(&log_sink_);
     }
 
+    /**
+     * Allocates @ref uavcan::Subscriber in the heap using shared pointer.
+     * The subscriber will be started immediately.
+     * @throws uavcan_linux::Exception.
+     */
     template <typename DataType>
     std::shared_ptr<uavcan::Subscriber<DataType>>
     makeSubscriber(const typename uavcan::Subscriber<DataType>::Callback& cb)
@@ -164,6 +188,11 @@ public:
         return p;
     }
 
+    /**
+     * Allocates @ref uavcan::Publisher in the heap using shared pointer.
+     * The publisher will be initialized immediately.
+     * @throws uavcan_linux::Exception.
+     */
     template <typename DataType>
     std::shared_ptr<uavcan::Publisher<DataType>>
     makePublisher(uavcan::MonotonicDuration tx_timeout = uavcan::Publisher<DataType>::getDefaultTxTimeout())
@@ -174,6 +203,11 @@ public:
         return p;
     }
 
+    /**
+     * Allocates @ref uavcan::ServiceServer in the heap using shared pointer.
+     * The server will be started immediately.
+     * @throws uavcan_linux::Exception.
+     */
     template <typename DataType>
     std::shared_ptr<uavcan::ServiceServer<DataType>>
     makeServiceServer(const typename uavcan::ServiceServer<DataType>::Callback& cb)
@@ -183,6 +217,11 @@ public:
         return p;
     }
 
+    /**
+     * Allocates @ref uavcan::ServiceClient in the heap using shared pointer.
+     * The service client will be initialized immediately.
+     * @throws uavcan_linux::Exception.
+     */
     template <typename DataType>
     std::shared_ptr<uavcan::ServiceClient<DataType>>
     makeServiceClient(const typename uavcan::ServiceClient<DataType>::Callback& cb)
@@ -193,6 +232,11 @@ public:
         return p;
     }
 
+    /**
+     * Allocates @ref uavcan_linux::BlockingServiceClient in the heap using shared pointer.
+     * The service client will be initialized immediately.
+     * @throws uavcan_linux::Exception.
+     */
     template <typename DataType>
     std::shared_ptr<BlockingServiceClient<DataType>>
     makeBlockingServiceClient()
@@ -202,6 +246,10 @@ public:
         return p;
     }
 
+    /**
+     * Allocates @ref uavcan::Timer in the heap using shared pointer.
+     * The timer will be started immediately in one-shot mode.
+     */
     TimerPtr makeTimer(uavcan::MonotonicTime deadline, const typename uavcan::Timer::Callback& cb)
     {
         TimerPtr p(new uavcan::Timer(*this));
@@ -210,6 +258,10 @@ public:
         return p;
     }
 
+    /**
+     * Allocates @ref uavcan::Timer in the heap using shared pointer.
+     * The timer will be started immediately in periodic mode.
+     */
     TimerPtr makeTimer(uavcan::MonotonicDuration period, const typename uavcan::Timer::Callback& cb)
     {
         TimerPtr p(new uavcan::Timer(*this));
@@ -226,6 +278,8 @@ typedef std::shared_ptr<Node> NodePtr;
 
 /**
  * Constructs Node with explicitly specified ClockAdjustmentMode.
+ * Please consider using the overload with fewer parameters instead.
+ * @throws uavcan_linux::Exception.
  */
 static inline NodePtr makeNode(const std::vector<std::string>& iface_names, ClockAdjustmentMode clock_adjustment_mode)
 {
@@ -241,7 +295,10 @@ static inline NodePtr makeNode(const std::vector<std::string>& iface_names, Cloc
 }
 
 /**
- * This is the preferred way to make Node.
+ * Use this function to create a node instance.
+ * It accepts the list of interface names to use for the new node, e.g. "can1", "vcan2", "slcan0".
+ * Clock adjustment mode will be detected automatically.
+ * @throws uavcan_linux::Exception.
  */
 static inline NodePtr makeNode(const std::vector<std::string>& iface_names)
 {