Update serialization/deserialization API documentation.

rmw/include/rmw/rmw.h

@@ -556,7 +556,14 @@ rmw_publisher_assert_liveliness(const rmw_publisher_t * publisher);
 /**
  * The ROS message is serialized into a byte stream contained within the
  * rmw_serialized_message_t structure.
- * The serialization format depends on the underlying middleware.
+ * The serialization format depends on the underlying implementation.
+ *
+ * \pre Given ROS message must be a valid non-null instance, initialized
+ *   by the caller and matching the provided typesupport.
+ * \pre Given typesupport must be a valid non-null instance, as provided
+ *   by `rosidl` APIs.
+ * \pre Given serialized message must be a valid non-null instance, initialized
+ *   by the caller.
  *
  * \param[in] ros_message the typed ROS message
  * \param[in] type_support the typesupport for the ROS message
@@ -577,10 +584,16 @@ rmw_serialize(
 /**
  * The given rmw_serialized_message_t's internal byte stream buffer is deserialized
  * into the given ROS message.
- * The ROS message must already be allocated and initialized, and must match
- * the given typesupport structure.
  * The serialization format expected in the rmw_serialized_message_t depends on the
- * underlying middleware.
+ * underlying implementation.
+ *
+ * \pre Given serialized message must be a valid non-null instance, such
+ *   as that returned by `rmw_serialize()`, matching provided typesupport
+ *   and ROS message.
+ * \pre Given typesupport must be a valid non-null instance, as provided
+ *   by `rosidl` APIs.
+ * \pre Given ROS message must be a valid non-null instance, initialized
+ *   by the caller.
  *
  * \param[in] serialized_message the serialized message holding the byte stream
  * \param[in] type_support the typesupport for the typed ros message

rmw/include/rmw/serialized_message.h

@@ -29,9 +29,49 @@ extern "C"
  * more complex and is therefore aliased.
  */
 typedef rcutils_uint8_array_t rmw_serialized_message_t;
+
+/// Return a zero initialized serialized message struct.
 #define rmw_get_zero_initialized_serialized_message rcutils_get_zero_initialized_uint8_array
+
+/// Initialize a serialized message, zero initializing its contents.
+/**
+ * \param[inout] serialized_message a pointer to the serialized message to initialize
+ * \param[in] message_capacity the size of the memory to allocate
+ * \param[in] allocator the allocator to use for the memory allocation
+ * \return `RMW_RET_OK` if successful, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or
+ * \return 'RMW_RET_BAD_ALLOC` if no memory could be allocated correctly
+ * \return `RMW_RET_ERROR` if an unexpected error occurs
+ */
 #define rmw_serialized_message_init rcutils_uint8_array_init
+
+/// Finalize a serialized message.
+/**
+ * Passing an uninitialized instance to this function leads to undefined
+ * behavior.
+ *
+ * \param[in] serialized_message pointer to the serialized message to be cleaned up
+ * \return `RMW_RET_OK` if successful, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if the serialized_message argument is invalid
+ * \return `RMW_RET_ERROR` if an unexpected error occurs
+ */
 #define rmw_serialized_message_fini rcutils_uint8_array_fini
+
+/// Resize the internal buffer of the serialized message.
+/**
+ * The internal buffer of the serialized message can be resized dynamically if needed.
+ * If the new size is smaller than the current capacity, then the memory is
+ * truncated.
+ * Be aware, that this might deallocate the memory and therefore invalidates any
+ * pointers to this storage.
+ *
+ * \param[inout] serialized_message pointer to the serialized message to be resized
+ * \param[in] new_size the new size of the internal buffer
+ * \return `RMW_RET_OK` if successful, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if new_size is set to zero
+ * \return `RMW_RET_BAD_ALLOC` if memory allocation failed, or
+ * \return `RMW_RET_ERROR` if an unexpected error occurs
+ */
 #define rmw_serialized_message_resize rcutils_uint8_array_resize
 
 #if __cplusplus