mark up all the functions to document

rclcpp/include/rclcpp/executor.hpp

@@ -36,6 +36,15 @@ namespace rclcpp
 namespace executor
 {
 
+/// Coordinates the order and timing of available communication tasks.
+/* Executor provides spin functions (including spin_node_once and spin_some). 
+ * It coordinates the nodes and callback groups by looking for available work and completing it,
+ * based on the threading or concurrency scheme provided by the subclass implementation.
+ * An example of available work is executing a subscription callback, or a timer callback.
+ * The executor structure allows for a decoupling of the communication graph and the execution
+ * model.
+ * See SingleThreadedExecutor and MultiThreadedExecutor for examples of execution paradigms.
+ */
 class Executor
 {
   friend class memory_strategy::MemoryStrategy;
@@ -43,6 +52,8 @@ class Executor
 public:
   RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(Executor);
 
+  /// Default constructor.
+  // \param[in] ms The memory strategy to be used with this executor.
   explicit Executor(memory_strategy::MemoryStrategy::SharedPtr ms =
     memory_strategy::create_default_strategy())
   : interrupt_guard_condition_(rmw_create_guard_condition()),
@@ -50,8 +61,10 @@ public:
   {
   }
 
+  /// Default destructor.
   virtual ~Executor()
   {
+    // Try to deallocate the interrupt guard condition.
     if (interrupt_guard_condition_ != nullptr) {
       rmw_ret_t status = rmw_destroy_guard_condition(interrupt_guard_condition_);
       if (status != RMW_RET_OK) {
@@ -61,8 +74,17 @@ public:
     }
   }
 
+  /// Do work periodically as it becomes available to us. Blocking call, may block indefinitely.
+  // It is up to the implementation of Executor to implement spin.
   virtual void spin() = 0;
 
+  /// Add a node to the executor.
+  /* An executor can have zero or more nodes which provide work during `spin` functions.
+   * \param[in] node_ptr Shared pointer to the node to be added.
+   * \param[in] notify True to trigger the interrupt guard condition during this function. If
+   * the executor is blocked at the rmw layer while waiting for work and it is notified that a new
+   * node was added, it will wake up.
+   */
   virtual void
   add_node(rclcpp::node::Node::SharedPtr & node_ptr, bool notify = true)
   {
@@ -84,6 +106,12 @@ public:
     }
   }
 
+  /// Remove a node from the executor.
+  /* \param[in] node_ptr Shared pointer to the node to remove.
+   * \param[in] notify True to trigger the interrupt guard condition and wake up the executor.
+   * This is useful if the last node was removed from the executor while the executor was blocked
+   * waiting for work in another thread, because otherwise the executor would never be notified.
+   */
   virtual void
   remove_node(rclcpp::node::Node::SharedPtr & node_ptr, bool notify = true)
   {
@@ -108,6 +136,11 @@ public:
     }
   }
 
+  /// Add a node to executor, complete the next available unit of work, and remove the node.
+  /* \param[in] node Shared pointer to the node to add.
+   * \param[in] timeout How long to wait for work to become available. Negative values cause
+   * spin_node_once to block indefinitely 
+   */
   template<typename T = std::milli>
   void spin_node_once(rclcpp::node::Node::SharedPtr & node,
     std::chrono::duration<int64_t, T> timeout = std::chrono::duration<int64_t, T>(-1))
@@ -121,6 +154,7 @@ public:
     this->remove_node(node, false);
   }
 
+// TODO
   void spin_node_some(rclcpp::node::Node::SharedPtr & node)
   {
     this->add_node(node, false);
@@ -128,6 +162,7 @@ public:
     this->remove_node(node, false);
   }
 
+// TODO
   virtual void spin_some()
   {
     while (AnyExecutable::SharedPtr any_exec =
@@ -137,6 +172,7 @@ public:
     }
   }
 
+// TODO
   // Support dynamic switching of memory strategy
   void
   set_memory_strategy(memory_strategy::MemoryStrategy::SharedPtr memory_strategy)
@@ -149,6 +185,7 @@ public:
 
 protected:
   void
+// TODO
   execute_any_executable(AnyExecutable::SharedPtr & any_exec)
   {
     if (!any_exec) {

rclcpp/include/rclcpp/executors/single_threaded_executor.hpp

@@ -36,6 +36,7 @@ namespace executors
 namespace single_threaded_executor
 {
 
+// TODO
 class SingleThreadedExecutor : public executor::Executor
 {
 public:

rclcpp/include/rclcpp/memory_strategy.hpp

@@ -30,6 +30,7 @@ class Executor;
 namespace memory_strategy
 {
 
+// TODO
 class MemoryStrategy
 {
 

rclcpp/include/rclcpp/message_memory_strategy.hpp

@@ -24,6 +24,7 @@ namespace rclcpp
 namespace message_memory_strategy
 {
 
+// TODO
 template<typename MessageT>
 class MessageMemoryStrategy
 {

rclcpp/include/rclcpp/node.hpp

@@ -96,6 +96,7 @@ struct function_traits<ReturnTypeT (ClassT::*)(Args ...) const>
  *
  * This is the single point of entry for creating publishers and subscribers.
  */
+// TODO
 class Node
 {
   friend class rclcpp::executor::Executor;
@@ -103,6 +104,7 @@ class Node
 public:
   RCLCPP_SMART_PTR_DEFINITIONS(Node);
 
+// TODO: ALL public functions
   /* Create a node based on the node name. */
   Node(const std::string & node_name, bool use_intra_process_comms = false);
   /* Create a node based on the node name and a rclcpp::context::Context. */

rclcpp/include/rclcpp/publisher.hpp

@@ -39,10 +39,12 @@ class Node;
 namespace publisher
 {
 
+// TODO
 class Publisher
 {
   friend rclcpp::node::Node;
 
+// TODO
 public:
   RCLCPP_SMART_PTR_DEFINITIONS(Publisher);
 

rclcpp/include/rclcpp/strategies/message_pool_memory_strategy.hpp

@@ -25,6 +25,7 @@ namespace strategies
 namespace message_pool_memory_strategy
 {
 
+// TODO
 template<typename MessageT, size_t Size,
 typename std::enable_if<rosidl_generator_traits::has_fixed_size<MessageT>::value>::type * =
 nullptr>

rclcpp/include/rclcpp/strategies/static_memory_strategy.hpp

@@ -27,6 +27,7 @@ namespace memory_strategies
 
 namespace static_memory_strategy
 {
+// TODO
 struct ObjectPoolBounds
 {
 public:
@@ -80,6 +81,7 @@ public:
 };
 
 
+// TODO
 class StaticMemoryStrategy : public memory_strategy::MemoryStrategy
 {
 public:

rclcpp/include/rclcpp/subscription.hpp

@@ -49,6 +49,7 @@ class SubscriptionBase
 {
   friend class rclcpp::executor::Executor;
 
+// TODO
 public:
   RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(SubscriptionBase);
 
@@ -113,11 +114,13 @@ private:
 
 };
 
+// TODO
 template<typename MessageT>
 class Subscription : public SubscriptionBase
 {
   friend class rclcpp::node::Node;
 
+// TODO
 public:
   using CallbackType = std::function<void(const std::shared_ptr<MessageT> &)>;
   RCLCPP_SMART_PTR_DEFINITIONS(Subscription);

rclcpp/include/rclcpp/timer.hpp

@@ -82,6 +82,7 @@ protected:
 
 };
 
+// TODO
 template<class Clock = std::chrono::high_resolution_clock>
 class GenericTimer : public TimerBase
 {

rclcpp/include/rclcpp/utilities.hpp

@@ -98,6 +98,7 @@ RMW_THREAD_LOCAL size_t thread_id = 0;
 namespace utilities
 {
 
+// TODO
 void
 init(int argc, char * argv[])
 {
@@ -138,12 +139,14 @@ init(int argc, char * argv[])
   }
 }
 
+// TODO
 bool
 ok()
 {
   return ::g_signal_status == 0;
 }
 
+// TODO
 void
 shutdown()
 {
@@ -163,6 +166,7 @@ get_global_sigint_guard_condition()
   return ::g_sigint_guard_cond_handle;
 }
 
+// TODO
 bool
 sleep_for(const std::chrono::nanoseconds & nanoseconds)
 {