Documentation: action, message, service typesupport and message bounds

rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h

@@ -27,6 +27,10 @@ extern "C"
 
 typedef struct rosidl_action_type_support_t rosidl_action_type_support_t;
 
+/// Contains rosidl action type support data.
+/*
+ * Actions are built based on services(goal, result and cancel) and message (feedback and status).
+ */
 struct rosidl_action_type_support_t
 {
   const rosidl_service_type_support_t * goal_service_type_support;
@@ -36,6 +40,12 @@ struct rosidl_action_type_support_t
   const rosidl_message_type_support_t * status_message_type_support;
 };
 
+/// Get the action type support given a provided action and package.
+/*
+ * \param PkgName name of the package that contains the action
+ * \param Name action name
+ * \return a rosidl_action_type_support_t struct if found, otherwise NULL.
+ */
 #define ROSIDL_GET_ACTION_TYPE_SUPPORT(PkgName, Name) \
   ROSIDL_TYPESUPPORT_INTERFACE__ACTION_SYMBOL_NAME( \
     rosidl_typesupport_c, PkgName, action, Name)()

rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h

@@ -28,21 +28,51 @@ typedef struct rosidl_message_type_support_t rosidl_message_type_support_t;
 typedef const rosidl_message_type_support_t * (* rosidl_message_typesupport_handle_function)(
   const rosidl_message_type_support_t *, const char *);
 
+/// Contains rosidl message type support data
 struct rosidl_message_type_support_t
 {
+  /// String identifier for the type_support.
   const char * typesupport_identifier;
+  /// Pointer to the message type support library
   const void * data;
+  /// Pointer to the message type support handler function
   rosidl_message_typesupport_handle_function func;
 };
 
+/// Get the message type support handle specific to this identifier.
+/**
+ * The handle's message typesupport identifier function is returned or if the parameters are NULL
+ * then an assert will happen.
+ *
+ * \param handle Handle to message type support
+ * \param identifier The typesupport identifier to get the handle function for
+ * \return The associated message typesupport handle function.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 const rosidl_message_type_support_t * get_message_typesupport_handle(
   const rosidl_message_type_support_t * handle, const char * identifier);
 
+// Get the message type support handle function specific to this identifier.
+/**
+ * If the identifier is the same as this handle's typesupport_identifier the handle is simply
+ * returned or if the parameters are NULL then an assert will happen.
+ *
+ * \param handle Handle to message type support
+ * \param identifier The typesupport identifier to get the handle function for
+ * \return if the identifier match's the handle's identifier then the handle's function
+ *   is returned.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 const rosidl_message_type_support_t * get_message_typesupport_handle_function(
   const rosidl_message_type_support_t * handle, const char * identifier);
 
+/// Get the message type support given a provided action and package.
+/*
+ * \param PkgName Name of the package that contains the message
+ * \param MsgSubfolder name of the subfolder (for example: msg)
+ * \param MsgName message name
+ * \return a rosidl_message_type_support_t struct if founded, otherwise NULL.
+ */
 #define ROSIDL_GET_MSG_TYPE_SUPPORT(PkgName, MsgSubfolder, MsgName) \
   ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME( \
     rosidl_typesupport_c, PkgName, MsgSubfolder, MsgName)()

rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h

@@ -30,19 +30,47 @@ typedef const rosidl_runtime_c__Sequence__bound * (* rosidl_runtime_c__bound_han
 
 struct rosidl_runtime_c__Sequence__bound
 {
+  /// String identifier for the type_support.
   const char * typesupport_identifier;
+  /// Pointer to type support handle function
   const void * data;
   rosidl_runtime_c__bound_handle_function func;
 };
 
+/// Get the message bounds handle specific to this identifier.
+/**
+ * The handle's sequence bound is simply returned or if the parameters are NULL then an assert
+ * will happen.
+ *
+ * \param handle Handle to service type support
+ * \param identifier The identifier to get the handle for
+ * \return The associated sequence bound handle function.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 const rosidl_runtime_c__Sequence__bound * get_sequence_bound_handle(
   const rosidl_runtime_c__Sequence__bound * handle, const char * identifier);
 
+/// Get the message bounds handle function specific to this identifier.
+/**
+ * If the identifier is the same as this handle function's identifier the handle is simply returned
+ * or if the parameters are NULL then an assert will happen.
+ *
+ * \param handle Handle to service type support
+ * \param identifier The identifier to get the handle function for
+ * \return if the identifier match's the handle's identifier then the handle's function
+ *   is returned.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 const rosidl_runtime_c__Sequence__bound * get_sequence_bound_handle_function(
   const rosidl_runtime_c__Sequence__bound * handle, const char * identifier);
 
+/// Get the sequence bounds given a provided action and package.
+/*
+ * \param PkgName Name of the package that contains the message
+ * \param MsgSubfolder name of the subfolder (foe example: msg)
+ * \param MsgName message name
+ * \return a rosidl_message_bounds_t struct if founded, otherwise NULL.
+ */
 #define ROSIDL_GET_SEQUENCE_BOUNDS(PkgName, MsgSubfolder, MsgName) \
   ROSIDL_BOUNDS_INTERFACE__MESSAGE_SYMBOL_NAME( \
     rosidl_typesupport_c, PkgName, MsgSubfolder, MsgName)()

rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h

@@ -29,21 +29,51 @@ typedef struct rosidl_service_type_support_t rosidl_service_type_support_t;
 typedef const rosidl_service_type_support_t * (* rosidl_service_typesupport_handle_function)(
   const rosidl_service_type_support_t *, const char *);
 
+/// Contains rosidl service type support data
 struct rosidl_service_type_support_t
 {
+  /// String identifier for the type_support.
   const char * typesupport_identifier;
+  /// Pointer to the service type support library
   const void * data;
+  /// Pointer to the service type support handler function
   rosidl_service_typesupport_handle_function func;
 };
 
+/// Get the service type support handle specific to this identifier.
+/**
+ * The handle's message typesupport identifier function is returned or if the parameters are NULL
+ * then an assert will happen.
+ *
+ * \param handle Handle to service type support
+ * \param identifier The typesupport identifier to get the handle function for
+ * \return The associated service typesupport handle function.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 const rosidl_service_type_support_t * get_service_typesupport_handle(
   const rosidl_service_type_support_t * handle, const char * identifier);
 
+/// Get the service type support handle function specific to this identifier.
+/**
+* If the identifier is the same as this handle's typesupport_identifier the handle is simply
+* returned or if the parameters are NULL then an assert will happen.
+ *
+ * \param handle Handle to service type support
+ * \param identifier The typesupport identifier to get the handle function for
+ * \return if the identifier match's the handle's identifier then the handle's function
+ *   is returned.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 const rosidl_service_type_support_t * get_service_typesupport_handle_function(
   const rosidl_service_type_support_t * handle, const char * identifier);
 
+/// Get the service type support given a provided action and package.
+/*
+ * \param PkgName Name of the package that contains the service
+ * \param SrvSubfolder name of the subfolder (for example: srv)
+ * \param SrvName service name
+ * \return a rosidl_service_type_support_t struct if founded, otherwise NULL.
+ */
 #define ROSIDL_GET_SRV_TYPE_SUPPORT(PkgName, SrvSubfolder, SrvName) \
   ROSIDL_TYPESUPPORT_INTERFACE__SERVICE_SYMBOL_NAME( \
     rosidl_typesupport_c, PkgName, SrvSubfolder, SrvName)()

rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h

@@ -26,44 +26,115 @@ extern "C"
 #endif
 
 /// Initialize a rosidl_runtime_c__String structure.
-/* The contents of rosidl_runtime_c__String are initialized to a single null character ('\0').
+/*
+ * The contents of rosidl_runtime_c__String are initialized to a single null character ('\0').
  * The string initially has size 0 and capacity 1.
  * Size represents the size of the contents of the string, while capacity represents the overall
  * storage of the string (counting the null terminator).
  * All strings must be null-terminated.
+ * The rosidl_runtime_c__String structure should be deallocated using the given function
+ * rosidl_runtime_c__String__fini() when it is no longer needed.
+ * Call this function with an already initialized string will leak memory.
+ *
+ * \param[inout] str a pointer to a rosidl_runtime_c__String structure
+ * \return true if successful, false if the passed string pointer is null
+ *   or the memory allocation failed
  */
 ROSIDL_GENERATOR_C_PUBLIC
 bool
 rosidl_runtime_c__String__init(rosidl_runtime_c__String * str);
 
+/// Deallocate the memory of the rosidl_runtime_c__String structure.
+/*
+* Calling the function with an already deallocated sequence is a no-op.
+*
+* \param[inout] str a pointer to a rosidl_runtime_c__String structure to be finalized
+*/
 ROSIDL_GENERATOR_C_PUBLIC
 void
 rosidl_runtime_c__String__fini(rosidl_runtime_c__String * str);
 
+/// Assign the c string pointer of n characters to the rosidl_runtime_c__String structure.
+/*
+ * \param[inout] str a pointer to a string structure
+ * \param[in] value c string pointer to be assigned
+ * \param[in] n size of the value string
+ * \return true if successful, false if the passed string pointer is null
+ *   or if the passed value pointer is null or if the size is higher than SIZE_MAX
+ *   or if the memory reallocation failed.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 bool
 rosidl_runtime_c__String__assignn(
   rosidl_runtime_c__String * str, const char * value, size_t n);
 
+/// Assign the c string pointer to the rosidl_runtime_c__String structure.
+/*
+ *
+ * This function is identical to rosidl_runtime_c__String__assignn() except the length of the
+ * c string does not have to be given and therefore the c string must be null terminated.
+ *
+ * \see rosidl_runtime_c__String__assignn()
+ *
+ * \param[inout] str a pointer to a rosidl_runtime_c__String structure
+ * \param[in] value c string pointer to be assigned
+ * \return true if successful, false if the passed string pointer is null
+ *   or if the passed value pointer is null or if the size is higher than SIZE_MAX
+ *   or if the memory reallocation failed.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 bool
 rosidl_runtime_c__String__assign(
   rosidl_runtime_c__String * str, const char * value);
 
+/// Initialize a rosidl_runtime_c__String__Sequence__init structure.
+/*
+ * The rosidl_runtime_c__String__Sequence is initialized with the size passed to the function.
+ * The rosidl_runtime_c__String__Sequence structure should be deallocated using the given function
+ * rosidl_runtime_c__String__Sequence__fini() when it is no longer needed.
+ * Call this function with an already initialized string sequence will leak memory.
+ *
+ * \param[inout] sequence a pointer to a string sequence
+ * \param[in] size represents the size of the string sequence
+ * \return true if successful, false if the passed string pointer is null
+ *   or the memory allocation failed
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 bool
 rosidl_runtime_c__String__Sequence__init(
   rosidl_runtime_c__String__Sequence * sequence, size_t size);
 
+/// Deallocate the memory of the string sequence structure.
+/*
+ * Calling the function with an already deallocated sequence is a no-op.
+ *
+ * \param[inout] sequence a pointer to a string sequence to be finalized
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 void
 rosidl_runtime_c__String__Sequence__fini(
   rosidl_runtime_c__String__Sequence * sequence);
 
+/// Create a rosidl_runtime_c__String__Sequence structure with a specific size.
+/*
+ * The string sequence initially has size and capacity equal to the size argument passed to the
+ * function.
+ * The rosidl_runtime_c__String__Sequence structure should be deallocated using the given function
+ * rosidl_runtime_c__String__Sequence__destroy() when it is no longer needed.
+ *
+ * \param[in] size of the desired string sequence
+ * \return a string sequence if initialization was successfully, otherwise NULL.
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 rosidl_runtime_c__String__Sequence *
 rosidl_runtime_c__String__Sequence__create(size_t size);
 
+/// Destroy a rosidl_runtime_c__String__Sequence structure.
+/*
+ * Calling the function with an already deallocated sequence is a no-op.
+ *
+ * \param[inout] sequence a pointer to a string sequence to be finalized
+ */
 ROSIDL_GENERATOR_C_PUBLIC
 void
 rosidl_runtime_c__String__Sequence__destroy(