Correct doxygen blocks

rclcpp/include/rclcpp/executor.hpp

@@ -36,8 +36,9 @@ namespace rclcpp
 namespace executor
 {
 
-/// Coordinates the order and timing of available communication tasks.
+/// Coordinate the order and timing of available communication tasks.
-/* Executor provides spin functions (including spin_node_once and spin_some).
+/**
+ * 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.
@@ -79,7 +80,8 @@ public:
   virtual void spin() = 0;
 
   /// Add a node to the executor.
-  /* An executor can have zero or more nodes which provide work during `spin` functions.
+  /**
+   * 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
@@ -107,7 +109,8 @@ public:
   }
 
   /// Remove a node from the executor.
-  /* \param[in] node_ptr Shared pointer to the node to remove.
+  /**
+   * \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.
@@ -137,7 +140,8 @@ public:
   }
 
   /// Add a node to executor, execute the next available unit of work, and remove the node.
-  /* \param[in] node Shared pointer to the node to add.
+  /**
+   * \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 (the default behavior). A timeout of 0 causes this
    * function to be non-blocking.
@@ -156,7 +160,8 @@ public:
   }
 
   /// Add a node, complete all immediately available work, and remove the node.
-  /* \param[in] node Shared pointer to the node to add.
+  /**
+   * \param[in] node Shared pointer to the node to add.
    */
   void spin_node_some(rclcpp::node::Node::SharedPtr & node)
   {
@@ -166,7 +171,8 @@ public:
   }
 
   /// Complete all available queued work without blocking.
-  /* This function can be overridden. The default implementation is suitable for a
+  /**
+   * This function can be overridden. The default implementation is suitable for a
    * single-threaded model of execution.
    * Adding subscriptions, timers, services, etc. with blocking callbacks will cause this function
    * to block (which may have unintended consequences).
@@ -181,7 +187,8 @@ public:
   }
 
   /// Support dynamic switching of the memory strategy.
-  /* Switching the memory strategy while the executor is spinning in another threading could have
+  /**
+   * Switching the memory strategy while the executor is spinning in another threading could have
    * unintended consequences.
    * \param[in] memory_strategy Shared pointer to the memory strategy to set.
    */
@@ -196,8 +203,9 @@ public:
 
 protected:
   /// Find the next available executable and do the work associated with it.
-  // \param[in] any_exec Union structure that can hold any executable type (timer, subscription,
+  /** \param[in] any_exec Union structure that can hold any executable type (timer, subscription,
-  // service, client).
+   * service, client).
+   */
   void
   execute_any_executable(AnyExecutable::SharedPtr & any_exec)
   {

rclcpp/include/rclcpp/memory_strategy.hpp

@@ -31,7 +31,8 @@ namespace memory_strategy
 {
 
 /// Delegate for handling memory allocations while the Executor is executing.
-/* By default, the memory strategy dynamically allocates memory for structures that come in from
+/**
+ * By default, the memory strategy dynamically allocates memory for structures that come in from
  * the rmw implementation after the executor waits for work, based on the number of entities that
  * come through.
  */
@@ -44,7 +45,8 @@ public:
   RCLCPP_SMART_PTR_DEFINITIONS(MemoryStrategy);
 
   /// Borrow memory for storing data for subscriptions, services, clients, or guard conditions.
-  /* The default implementation ignores the handle type and dynamically allocates the memory.
+  /**
+   * The default implementation ignores the handle type and dynamically allocates the memory.
    * \param[in] The type of entity that this function is requesting for.
    * \param[in] The number of handles to borrow.
    * \return Pointer to the allocated handles.
@@ -56,7 +58,8 @@ public:
   }
 
   /// Return the memory borrowed in borrow_handles.
-  /* return_handles should always mirror the way memory was borrowed in borrow_handles.
+  /**
+   * return_handles should always mirror the way memory was borrowed in borrow_handles.
    * \param[in] The type of entity that this function is returning.
    * \param[in] Pointer to the handles returned.
    */
@@ -74,7 +77,8 @@ public:
   }
 
   /// Implementation of a general-purpose allocation function.
-  /* \param[in] size Number of bytes to allocate.
+  /**
+   * \param[in] size Number of bytes to allocate.
    * \return Pointer to the allocated chunk of memory.
    */
   virtual void * alloc(size_t size)
@@ -86,7 +90,8 @@ public:
   }
 
   /// Implementation of a general-purpose free.
-  /* \param[in] Pointer to deallocate.
+  /**
+   * \param[in] Pointer to deallocate.
    */
   virtual void free(void * ptr)
   {

rclcpp/include/rclcpp/node.hpp

@@ -101,14 +101,16 @@ public:
   RCLCPP_SMART_PTR_DEFINITIONS(Node);
 
   /// Create a new node with the specified name.
-  /* \param[in] node_name Name of the node.
+  /**
+   * \param[in] node_name Name of the node.
    * \param[in] use_intra_process_comms True to use the optimized intra-process communication
    * pipeline to pass messages between nodes in the same process using shared memory.
    */
   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.
-  /* \param[in] node_name Name of the node.
+  /**
+   * \param[in] node_name Name of the node.
    * \param[in] context The context for the node (usually represents the state of a process).
    * \param[in] use_intra_process_comms True to use the optimized intra-process communication
    * pipeline to pass messages between nodes in the same process using shared memory.
@@ -127,7 +129,8 @@ public:
   create_callback_group(rclcpp::callback_group::CallbackGroupType group_type);
 
   /// Create and return a Publisher.
-  /* \param[in] topic_name The topic for this publisher to publish on.
+  /**
+   * \param[in] topic_name The topic for this publisher to publish on.
    * \param[in] qos_profile The quality of service profile to pass on to the rmw implementation.
    * \return Shared pointer to the created publisher.
    */
@@ -137,7 +140,8 @@ public:
     const std::string & topic_name, const rmw_qos_profile_t & qos_profile);
 
   /// Create and return a Subscription.
-  /* \param[in] topic_name The topic to subscribe on.
+  /**
+   * \param[in] topic_name The topic to subscribe on.
    * \param[in] qos_profile The quality of service profile to pass on to the rmw implementation.
    * \param[in] callback The user-defined callback function.
    * \param[in] group The callback group for this subscription. NULL for no callback group.
@@ -161,7 +165,8 @@ public:
     msg_mem_strat = nullptr);
 
   /// Create a timer.
-  /* \param[in] period Time interval between triggers of the callback.
+  /**
+   * \param[in] period Time interval between triggers of the callback.
    * \param[in] callback User-defined callback function.
    * \param[in] group Callback group to execute this timer's callback in.
    */
@@ -172,7 +177,8 @@ public:
     rclcpp::callback_group::CallbackGroup::SharedPtr group = nullptr);
 
   /// Create a timer with a sub-nanosecond precision update period.
-  /* \param[in] period Time interval between triggers of the callback.
+  /**
+   * \param[in] period Time interval between triggers of the callback.
    * \param[in] callback User-defined callback function.
    * \param[in] group Callback group to execute this timer's callback in.
    */

rclcpp/include/rclcpp/publisher.hpp

@@ -48,7 +48,8 @@ public:
   RCLCPP_SMART_PTR_DEFINITIONS(Publisher);
 
   /// Default constructor.
-  /* Typically, a publisher is not created through this method, but instead is created through a
+  /**
+   * Typically, a publisher is not created through this method, but instead is created through a
    * call to `Node::create_publisher`.
    * \param[in] node_handle The corresponding rmw representation of the owner node.
    * \param[in] publisher_handle The rmw publisher handle corresponding to this publisher.
@@ -96,7 +97,8 @@ public:
   }
 
   /// Send a message to the topic for this publisher.
-  /* This function is templated on the input message type, MessageT.
+  /**
+   * This function is templated on the input message type, MessageT.
    * \param[in] msg A shared pointer to the message to send.
    */
   template<typename MessageT>
@@ -159,7 +161,8 @@ public:
   }
 
   /// Compare this publisher to a gid.
-  /* Note that this function calls the next function.
+  /**
+   * Note that this function calls the next function.
    * \param[in] gid Reference to a gid.
    * \return True if the publisher's gid matches the input.
    */
@@ -170,7 +173,8 @@ public:
   }
 
   /// Compare this publisher to a pointer gid.
-  /* A wrapper for comparing this publisher's gid to the input using rmw_compare_gids_equal.
+  /**
+   * A wrapper for comparing this publisher's gid to the input using rmw_compare_gids_equal.
    * \param[in] gid A pointer to a gid.
    * \return True if this publisher's gid matches the input.
    */

rclcpp/include/rclcpp/strategies/message_pool_memory_strategy.hpp

@@ -26,7 +26,8 @@ namespace message_pool_memory_strategy
 {
 
 /// Completely static memory allocation strategy for messages.
-/* Templated on the type of message pooled by this class and the size of the message pool.
+/**
+ * Templated on the type of message pooled by this class and the size of the message pool.
  * Templating allows the program to determine the memory required for this object at compile time.
  * The size of the message pool should be at least the largest number of concurrent accesses to
  * the subscription (usually the number of threads).
@@ -51,7 +52,8 @@ public:
   }
 
   /// Borrow a message from the message pool.
-  /* Manage the message pool ring buffer.
+  /**
+   * Manage the message pool ring buffer.
    * Throw an exception if the next message was not available.
    * \return Shared pointer to the borrowed message.
    */
@@ -70,7 +72,8 @@ public:
   }
 
   /// Return a message to the message pool.
-  /* Manage metadata in the message pool ring buffer to release the message.
+  /**
+   * Manage metadata in the message pool ring buffer to release the message.
    * \param[in] msg Shared pointer to the message to return.
    */
   void return_message(std::shared_ptr<MessageT> & msg)

rclcpp/include/rclcpp/strategies/static_memory_strategy.hpp

@@ -48,7 +48,8 @@ public:
   // Setters implement named parameter idiom/method chaining
 
   /// Set the maximum number of subscriptions.
-  /* \param[in] subscriptions Maximum number of subscriptions.
+  /**
+   * \param[in] subscriptions Maximum number of subscriptions.
    * \return Reference to this object, for method chaining.
    */
   ObjectPoolBounds & set_max_subscriptions(size_t subscriptions)
@@ -58,7 +59,8 @@ public:
   }
 
   /// Set the maximum number of services.
-  /* \param[in] services Maximum number of services.
+  /**
+   * \param[in] services Maximum number of services.
    * \return Reference to this object, for method chaining.
    */
   ObjectPoolBounds & set_max_services(size_t services)
@@ -68,7 +70,8 @@ public:
   }
 
   /// Set the maximum number of clients.
-  /* \param[in] clients Maximum number of clients.
+  /**
+   * \param[in] clients Maximum number of clients.
    * \return Reference to this object, for method chaining.
    */
   ObjectPoolBounds & set_max_clients(size_t clients)
@@ -78,7 +81,8 @@ public:
   }
 
   /// Set the maximum number of guard conditions.
-  /* \param[in] guard conditions Maximum number of guard conditions.
+  /**
+   * \param[in] guard conditions Maximum number of guard conditions.
    * \return Reference to this object, for method chaining.
    */
   ObjectPoolBounds & set_max_guard_conditions(size_t guard_conditions)
@@ -88,7 +92,8 @@ public:
   }
 
   /// Set the maximum number of executables.
-  /* \param[in] executables Maximum number of executables.
+  /**
+   * \param[in] executables Maximum number of executables.
    * \return Reference to this object, for method chaining.
    */
   ObjectPoolBounds & set_max_executables(size_t executables)
@@ -98,7 +103,8 @@ public:
   }
 
   /// Set the maximum memory pool size.
-  /* \param[in] executables Maximum memory pool size.
+  /**
+   * \param[in] executables Maximum memory pool size.
    * \return Reference to this object, for method chaining.
    */
   ObjectPoolBounds & set_memory_pool_size(size_t pool)
@@ -110,7 +116,8 @@ public:
 
 
 /// Static memory allocation alternative to the default memory strategy.
-/* The name is a bit of a misnomer. The memory managed by this class is actually allocated
+/**
+ * The name is a bit of a misnomer. The memory managed by this class is actually allocated
  * dynamically in the constructor, but no subsequent accesses to the class (besides the destructor)
  * allocate or free memory.
  * StaticMemoryStrategy puts a hard limit on the number of subscriptions, etc. that can be executed
@@ -190,7 +197,8 @@ public:
   }
 
   /// Borrow handles by returning a pointer to the preallocated object pool for the specified type.
-  /* \param[in] The type of entity that this function is requesting for.
+  /**
+   * \param[in] The type of entity that this function is requesting for.
    * \param[in] The number of handles to borrow.
    * \return Pointer to the allocated handles.
    */
@@ -228,7 +236,8 @@ public:
   }
 
   /// Return the borrowed handles by clearing the object pool for the correspondign type.
-  /* \param[in] The type of entity that this function is returning.
+  /**
+   * \param[in] The type of entity that this function is returning.
    * \param[in] Pointer to the handles returned.
    */
   void return_handles(HandleType type, void ** handles)
@@ -287,7 +296,8 @@ public:
   }
 
   /// General allocate: reserve space in the memory pool reserved by this function.
-  /* \param[in] size Number of bytes to allocate.
+  /**
+   * \param[in] size Number of bytes to allocate.
    * \return Pointer to the allocated chunk of memory.
    */
   void * alloc(size_t size)
@@ -310,7 +320,8 @@ public:
   }
 
   /// Release the allocated memory in the memory pool.
-  /* \param[in] Pointer to deallocate.
+  /**
+   * \param[in] Pointer to deallocate.
    */
   void free(void * ptr)
   {

rclcpp/include/rclcpp/subscription.hpp

@@ -55,7 +55,8 @@ public:
   RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(SubscriptionBase);
 
   /// Default constructor.
-  /* \param[in] node_handle The rmw representation of the node that owns this subscription.
+  /**
+   * \param[in] node_handle The rmw representation of the node that owns this subscription.
    * \param[in] topic_name Name of the topic to subscribe to.
    * \param[in] ignore_local_publications True to ignore local publications (unused).
    */
@@ -107,7 +108,8 @@ public:
   virtual std::shared_ptr<void> create_message() = 0;
 
   /// Check if we need to handle the message, and execute the callback if we do.
-  /* \param[in] message Shared pointer to the message to handle.
+  /**
+   * \param[in] message Shared pointer to the message to handle.
    * \param[in] sender_id Global identifier of the entity that sent this message.
    */
   virtual void handle_message(std::shared_ptr<void> & message, const rmw_gid_t * sender_id) = 0;
@@ -144,7 +146,8 @@ public:
   RCLCPP_SMART_PTR_DEFINITIONS(Subscription);
 
   /// Default constructor.
-  /* The constructor for a subscription is almost never called directly. Instead, subscriptions
+  /**
+   * The constructor for a subscription is almost never called directly. Instead, subscriptions
    * should be instantiated through Node::create_subscription.
    * \param[in] node_handle rmw representation of the node that owns this subscription.
    * \param[in] topic_name Name of the topic to subscribe to.
@@ -168,7 +171,8 @@ public:
   {}
 
   /// Support dynamically setting the message memory strategy.
-  /* Behavior may be undefined if called while the subscription could be executing.
+  /**
+   * Behavior may be undefined if called while the subscription could be executing.
    * \param[in] message_memory_strategy Shared pointer to the memory strategy to set.
    */
   void set_message_memory_strategy(

rclcpp/include/rclcpp/timer.hpp

@@ -76,7 +76,8 @@ public:
   virtual bool is_steady() = 0;
 
   /// Check if the timer needs to trigger the callback.
-  /* This function expects its caller to immediately trigger the callback after this function,
+  /**
+   * This function expects its caller to immediately trigger the callback after this function,
    * since it maintains the last time the callback was triggered.
    * \return True if the timer needs to trigger.
    */
@@ -100,7 +101,8 @@ public:
   RCLCPP_SMART_PTR_DEFINITIONS(GenericTimer);
 
   /// Default constructor.
-  /* \param[in] period The interval at which the timer fires.
+  /**
+   * \param[in] period The interval at which the timer fires.
    * \param[in] callback User-specified callback function.
    */
   GenericTimer(std::chrono::nanoseconds period, CallbackType callback)

rclcpp/include/rclcpp/utilities.hpp

@@ -54,9 +54,11 @@ struct sigaction old_action;
 void (* old_signal_handler)(int) = 0;
 #endif
 
-/// When the interrupt signal fires, the signal handler notifies the condition variable to wake up
+/// Handle the interrupt signal.
-/// and triggers the interrupt guard condition, so that all global threads managed by rclcpp
+/** When the interrupt signal fires, the signal handler notifies the condition variable to wake up
-/// are interrupted.
+ * and triggers the interrupt guard condition, so that all global threads managed by rclcpp
+ * are interrupted.
+ */
 void
 #ifdef HAS_SIGACTION
 signal_handler(int signal_value, siginfo_t * siginfo, void * context)
@@ -106,7 +108,8 @@ namespace utilities
 {
 
 /// Initialize communications via the rmw implementation and set up a global signal handler.
-/* \param[in] argc Number of arguments.
+/**
+ * \param[in] argc Number of arguments.
  * \param[in] argv Argument vector. Will eventually be used for passing options to rclcpp.
  */
 void
@@ -179,7 +182,8 @@ get_global_sigint_guard_condition()
 }
 
 /// Use the global condition variable to block for the specified amount of time.
-/* \param[in] nanoseconds A std::chrono::duration representing how long to sleep for.
+/**
+ * \param[in] nanoseconds A std::chrono::duration representing how long to sleep for.
  * \return True if the condition variable did not timeout.
  */
 bool