From 7f225172aea51e37c54d23dc1d6b77d20bb1d0c2 Mon Sep 17 00:00:00 2001 From: Christophe Bedard Date: Fri, 26 Apr 2024 13:50:25 -0700 Subject: [PATCH] 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 --- .../action_type_support_struct.h | 4 +-- .../message_type_support_struct.h | 2 +- .../include/rosidl_runtime_c/sequence_bound.h | 2 +- .../service_type_support_struct.h | 2 +- .../rosidl_runtime_c/string_functions.h | 17 +++++---- .../rosidl_runtime_c/u16string_functions.h | 36 ++++++++++--------- 6 files changed, 32 insertions(+), 31 deletions(-) diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h b/rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h index 62b45b036..007e098b0 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h +++ b/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. diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h b/rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h index 071cac27d..6b95a97ef 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h +++ b/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 diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h b/rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h index bce6ab5d7..256337ef3 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h +++ b/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 diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h b/rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h index c6009ecd3..3088568be 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h +++ b/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 diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h b/rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h index ef553df33..5f378220e 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h +++ b/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 diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/u16string_functions.h b/rosidl_runtime_c/include/rosidl_runtime_c/u16string_functions.h index c89afabfc..90a886ba1 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/u16string_functions.h +++ b/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,7 +169,7 @@ 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. @@ -175,7 +177,7 @@ rosidl_runtime_c__U16String__resize( * 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,13 +229,13 @@ 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 @@ -241,7 +243,7 @@ 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