Fix u16 docs and improve docs formatting (#805)

* Fix documentation of u16 sequence size param

* Clarify meaning of size param for *U16String__assignn_from_char

Signed-off-by: Christophe Bedard <christophe.bedard@apex.ai>

rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h

@@ -38,7 +38,7 @@ typedef const rosidl_runtime_c__type_description__TypeSource__Sequence *
 (* rosidl_action_get_type_description_sources_function)(const 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
@@ -57,7 +57,7 @@ struct rosidl_action_type_support_t
 };
 
 /// 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.

rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h

@@ -89,7 +89,7 @@ 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

rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h

@@ -65,7 +65,7 @@ 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

rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h

@@ -137,7 +137,7 @@ 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

rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h

@@ -26,7 +26,7 @@ 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 string initially has size 0 and capacity 1.
  * Size represents the size of the contents of the string, while capacity represents the overall
@@ -46,7 +46,7 @@ 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
@@ -86,7 +86,7 @@ rosidl_runtime_c__String__are_equal(
   const rosidl_runtime_c__String * lhs, const rosidl_runtime_c__String * rhs);
 
 /// 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
@@ -100,8 +100,7 @@ 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.
  *
@@ -119,7 +118,7 @@ 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.
@@ -137,7 +136,7 @@ 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
@@ -179,7 +178,7 @@ rosidl_runtime_c__String__Sequence__copy(
   rosidl_runtime_c__String__Sequence * output);
 
 /// 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
@@ -193,7 +192,7 @@ 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_runtime_c/include/rosidl_runtime_c/u16string_functions.h

@@ -26,7 +26,8 @@ extern "C"
 #endif
 
 /// Initialize a rosidl_runtime_c__U16String structure.
-/* The contents of rosidl_runtime_c__U16String are initialized to a single null character.
+/**
+ * The contents of rosidl_runtime_c__U16String are initialized to a single null character.
  * 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).
@@ -45,7 +46,7 @@ bool
 rosidl_runtime_c__U16String__init(rosidl_runtime_c__U16String * str);
 
 /// Deallocate the memory of the rosidl_runtime_c__U16String structure.
-/*
+/**
 * Calling the function with an already deallocated sequence is a no-op.
 *
 * \param[inout] str a pointer to a U16 string structure to be finalized
@@ -86,7 +87,7 @@ rosidl_runtime_c__U16String__copy(
   rosidl_runtime_c__U16String * output);
 
 /// Assign the uint16_t value of n characters to the rosidl_runtime_c__U16String structure.
-/*
+/**
  * This function returns `false` if memory cannot be allocated,
  * if the input uint16_t pointer is null or if the size is higher than SIZE_MAX.
  * In both cases no error message is set.
@@ -104,17 +105,18 @@ rosidl_runtime_c__U16String__assignn(
   rosidl_runtime_c__U16String * str, const uint16_t * value, size_t n);
 
 /// Assign the c string pointer value of n characters to the rosidl_runtime_c__U16String structure.
-/*
+/**
  * This function is identical to rosidl_runtime_c__U16String__assignn() except the type of the
- * value is c string pointer
+ * value is a c string pointer.
  *
  * \see rosidl_runtime_c__U16String__assignn()
  *
  * \param[inout] str a pointer to a U16 string structure
- * \param[in] value points to a sequence of 16 bit chars
- * \param[in] n size of the value string
+ * \param[in] value c string pointer to be assigned
+ * \param[in] n size of the value string as the number of 8 bit chars
  * \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 passed value pointer is null
+ *   or if the size is not even or is higher than SIZE_MAX
  *   or if the memory reallocation failed.
  */
 ROSIDL_GENERATOR_C_PUBLIC
@@ -123,7 +125,7 @@ rosidl_runtime_c__U16String__assignn_from_char(
   rosidl_runtime_c__U16String * str, const char * value, size_t n);
 
 /// Assign the uint16_t pointer to the rosidl_runtime_c__U16String structure.
-/*
+/**
  * This function is identical to rosidl_runtime_c__U16String__assignn() except the length of the
  * uint16_t does not have to be given.
  * rosidl_runtime_c__U16String__len() is being used to determine the length of the passed string.
@@ -142,7 +144,7 @@ rosidl_runtime_c__U16String__assign(
   rosidl_runtime_c__U16String * str, const uint16_t * value);
 
 /// Get the length of the uint16_t pointer.
-/*
+/**
  * This function returns the length of the input value pointer.
  *
  * \param[in] value points to a sequence of 16 bit chars for which the first null char is
@@ -154,7 +156,7 @@ size_t
 rosidl_runtime_c__U16String__len(const uint16_t * value);
 
 /// Resize the uint16_t pointer.
-/*
+/**
  * This function resize the input value pointer.
  *
  * \param[in] n the new size of the internal buffer
@@ -167,15 +169,15 @@ rosidl_runtime_c__U16String__resize(
   rosidl_runtime_c__U16String * str, size_t n);
 
 /// Initialize a U16 string sequence structure.
-/*
+/**
  * The rosidl_runtime_c__U16String__Sequence is initialized to the size passed to the function.
  * The U16 string sequence structure should be deallocated using the given
  * function rosidl_runtime_c__U16String__Sequence__fini() when it is no longer needed.
  * Calling this function with an already initialized U16 string sequence structure will leak
  * memory.
  *
  * \param[inout] sequence a pointer to a U16 string sequence structure
- * \param[in] size represents the size of the U16 string
+ * \param[in] size represents the size of the U16 string sequence
  * \return true if successful, false if the passed string pointer is null
  *   or the memory allocation failed
  */
@@ -185,7 +187,7 @@ rosidl_runtime_c__U16String__Sequence__init(
   rosidl_runtime_c__U16String__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 U16 string to be finalized
@@ -227,21 +229,21 @@ rosidl_runtime_c__U16String__Sequence__copy(
   rosidl_runtime_c__U16String__Sequence * output);
 
 /// Create a U16 string sequence structure with a specific size.
-/*
+/**
  * The U16 string sequence initially has size and capacity equal to the size
  * argument.
  * The U16 string sequence structure should be deallocated using the given
  * function rosidl_runtime_c__U16String__Sequence__destroy() when it is no longer needed.
  *
- * \param[in] size of the desired U16 string
+ * \param[in] size of the desired U16 string sequence
  * \return a U16 string sequence if initialization was successfully, otherwise NULL.
  */
 ROSIDL_GENERATOR_C_PUBLIC
 rosidl_runtime_c__U16String__Sequence *
 rosidl_runtime_c__U16String__Sequence__create(size_t size);
 
 /// Destroy a U16 string sequence structure.
-/*
+/**
  * Calling the function with an already deallocated sequence is a no-op.
  *
  * \param[inout] sequence a pointer to a U16 string sequence to be finalized