documentation for new functions

rmw/include/rmw/raw_message.h

@@ -25,21 +25,55 @@ extern "C"
 #include "rmw/types.h"
 #include "rmw/visibility_control.h"
 
+/// Create a zero initialized raw message struct
+/**
+ * \return rmw_message_raw_t a zero initialized raw message struct
+ */
 RMW_PUBLIC
 rmw_message_raw_t
 rmw_get_zero_initialized_raw_message(void);
 
+/// Initialize a newly created raw message struct
+/**
+ * Initialize a zero initialized raw message struct
+ * This function might leak if the raw message struct is already pre-initialized.
+ * If the capacity is set to 0, no memory is allocated and the internal buffer
+ * is still NULL.
+ * \return rmw_ret_t indicate whether the object was successfully initialized
+ * \param msg pointer to the to be initialized raw message struct
+ * \param buffer_capacity the size of the memory to allocate for the bytestream
+ * \param allocator the allocator to use for the memory allocation.
+ */
 RMW_PUBLIC
 rmw_ret_t
 rmw_raw_message_init(
   rmw_message_raw_t * msg,
   unsigned int buffer_capacity,
   const rcutils_allocator_t * allocator);
 
+/// Cleanup a raw message struct
+/**
+ * Deallocate and cleanup a raw message struct. This functions has to be created by a
+ * call to rmw_get_zero_initialized_raw_message prior to this or it might lead to
+ * undefined behavior.
+ * \return rmw_ret_t indicate whether the object was successfully cleaned up.
+ * \param msg pointer to the raw message to be cleaned up
+ */
 RMW_PUBLIC
 rmw_ret_t
 rmw_raw_message_fini(rmw_message_raw_t * msg);
 
+/// Resize the internal buffer for the message bytestream
+/**
+ * The internal buffer of the raw message can be resized dynamically if needed.
+ * If the new size is smaller than the current capacity, the memory is truncated.
+ * Be aware, that this will deallocate the memory and invalidates their pointers.
+ * If the new size is larger, new memory is getting allocated and the existing
+ * content is copied over.
+ * \return rmw_ret_t indicate whether the resizing was successful.
+ * \param msg pointer to the raw message struct which internal buffer is getting resized.
+ * \param new_size the new size of the internal buffer
+ */
 RMW_PUBLIC
 rmw_ret_t
 rmw_raw_message_resize(rmw_message_raw_t * msg, unsigned int new_size);

rmw/include/rmw/rmw.h

@@ -171,6 +171,17 @@ RMW_WARN_UNUSED
 rmw_ret_t
 rmw_publish(const rmw_publisher_t * publisher, const void * ros_message);
 
+/// publish an already serialized message
+/**
+ * An already serialized message can be sent. The publisher has to be registered with
+ * the correct message type and can thus send serialized data corresponding to it type.
+ * This function allows to send the serialized bytestream directly over the wire without
+ * having the need to serialize the message.
+ * A ROS message can be serialized manually via the rmw_serialize function.
+ * \return rmw_ret_t indicate whether the publish was successful.
+ * \param publisher the publisher object registered to send the message
+ * \param raw_message the serialized message holding the bytestream
+ */
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_ret_t
@@ -239,6 +250,19 @@ rmw_take_with_info(
   bool * taken,
   rmw_message_info_t * message_info);
 
+/// Receive a message in a serialized form
+/**
+ * The message is taken in its serialized form. In contrast to rmw_take, the message
+ * is not deserialized in its ROS type but rather returned as a bytestream.
+ * The subscriber has to be registered for a specific type. But instead of receiving
+ * the message as its corresponding message type, it is taken as a bytestream.
+ * If needed, this bytestream can then be deserialized in a ROS message with a call to
+ * rmw_deserialize.
+ * \return rmw_ret_t indicate whether the message was correctly received
+ * \param subscription subscription object registered for a specific message type.
+ * \param raw_message the message container holding the serialized bytestream
+ * \param taken boolean flag indicating if the message was taken correctly
+ */
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_ret_t
@@ -247,6 +271,13 @@ rmw_take_raw(
   rmw_message_raw_t * raw_message,
   bool * taken);
 
+/// Receive a message in a serialized form plus its subscription info
+/**
+ * The same function call as rmw_take, with additional connection information, such as GUID.
+ * \param subscription subscription object registered for a specific message type.
+ * \param raw_message the message container holding the serialized bytestream
+ * \param taken boolean flag indicating if the message was taken correctly
+ */
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_ret_t