Add documentation about bytes reader/writer (#724)

docs/api.rst

@@ -206,6 +206,66 @@ See details at :ref:`owned_types_concept`
 .. c:function:: const z_loaned_keyexpr_t * z_keyexpr_loan(const z_owned_keyexpr_t * keyexpr)
 .. c:function:: z_loaned_keyexpr_t * z_keyexpr_loan_mut(z_owned_keyexpr_t * keyexpr)
 
+Payload
+-------
+
+Types
+^^^^^
+
+see details at :ref:`owned_types_concept`
+
+.. c:type:: z_owned_bytes_t
+.. c:type:: z_loaned_bytes_t
+.. c:type:: z_moved_bytes_t
+
+.. c:type:: z_owned_bytes_writter_t
+.. c:type:: z_loaned_bytes_writter_t
+.. c:type:: z_moved_bytes_writter_t
+
+.. autoctype:: types.h::z_bytes_reader_t
+
+Functions
+^^^^^^^^^
+.. autocfunction:: primitives.h::z_bytes_empty
+.. autocfunction:: primitives.h::z_bytes_len
+.. autocfunction:: primitives.h::z_bytes_from_buf
+.. autocfunction:: primitives.h::z_bytes_from_slice
+.. autocfunction:: primitives.h::z_bytes_from_static_buf
+.. autocfunction:: primitives.h::z_bytes_from_static_str
+.. autocfunction:: primitives.h::z_bytes_from_str
+.. autocfunction:: primitives.h::z_bytes_from_string
+.. autocfunction:: primitives.h::z_bytes_copy_from_buf
+.. autocfunction:: primitives.h::z_bytes_copy_from_slice
+.. autocfunction:: primitives.h::z_bytes_copy_from_str
+.. autocfunction:: primitives.h::z_bytes_copy_from_string
+.. autocfunction:: primitives.h::z_bytes_to_slice
+.. autocfunction:: primitives.h::z_bytes_to_string
+
+.. autocfunction:: primitives.h::z_bytes_get_reader
+.. autocfunction:: primitives.h::z_bytes_reader_read
+.. autocfunction:: primitives.h::z_bytes_reader_remaining
+.. autocfunction:: primitives.h::z_bytes_reader_seek
+.. autocfunction:: primitives.h::z_bytes_reader_tell
+
+.. autocfunction:: primitives.h::z_bytes_writer_append
+.. autocfunction:: primitives.h::z_bytes_writer_empty
+.. autocfunction:: primitives.h::z_bytes_writer_finish
+.. autocfunction:: primitives.h::z_bytes_writer_write_all
+
+Ownership Functions
+^^^^^^^^^^^^^^^^^^^
+
+See details at :ref:`owned_types_concept`
+
+.. c:function:: void z_bytes_drop(z_moved_bytes_t * bytes) 
+.. c:function:: void z_bytes_clone(z_owned_bytes_t * dst, const z_loaned_bytes_t * bytes) 
+.. c:function:: const z_loaned_bytes_t * z_bytes_loan(const z_owned_bytes_t * bytes)
+.. c:function:: z_loaned_bytes_t * z_bytes_loan_mut(z_owned_bytes_t * bytes)
+
+.. c:function:: void z_bytes_writer_drop(z_moved_bytes_writer_t * bytes_writer) 
+.. c:function:: void z_bytes_writer_clone(z_owned_bytes_writer_t * dst, const z_loaned_bytes_writer_t * bytes_writer) 
+.. c:function:: const z_loaned_bytes_writer_t * z_bytes_writer_loan(const z_owned_bytes_writer_t * bytes_writer)
+.. c:function:: z_loaned_bytes_writer_t * z_bytes_writer_loan_mut(z_owned_bytes_writer_t * bytes_writer)
 
 Encoding
 --------

include/zenoh-pico/api/primitives.h

@@ -642,6 +642,7 @@ z_result_t z_bytes_from_str(z_owned_bytes_t *bytes, char *value, void (*deleter)
  *   ``0`` if conversion is successful, ``negative value`` otherwise.
  */
 z_result_t z_bytes_copy_from_str(z_owned_bytes_t *bytes, const char *value);
+
 /**
  * Converts a statically allocated constant null-terminated string into a :c:type:`z_owned_bytes_t` by aliasing.
  *
@@ -655,8 +656,10 @@ z_result_t z_bytes_copy_from_str(z_owned_bytes_t *bytes, const char *value);
 z_result_t z_bytes_from_static_str(z_owned_bytes_t *bytes, const char *value);
 
 /**
+ * Constructs an empty payload.
+ *
  * Parameters:
- *   bytes: Pointer to an unitialized :c:type:`z_lowned_bytes_t` instance.
+ *   bytes: Pointer to an unitialized :c:type:`z_loaned_bytes_t` instance.
  */
 void z_bytes_empty(z_owned_bytes_t *bytes);
 
@@ -747,9 +750,10 @@ size_t z_bytes_reader_read(z_bytes_reader_t *reader, uint8_t *dst, size_t len);
  *   origin: Origin for the new position.
  *
  * Return:
- *   ``0`` upon success, negative error code otherwise.
+ *   ``0`` in case of success, ``negative value`` otherwise.
  */
 z_result_t z_bytes_reader_seek(z_bytes_reader_t *reader, int64_t offset, int origin);
+
 /**
  * Gets the read position indicator.
  *
@@ -793,7 +797,7 @@ z_result_t z_bytes_writer_empty(z_owned_bytes_writer_t *writer);
 void z_bytes_writer_finish(z_moved_bytes_writer_t *writer, z_owned_bytes_t *bytes);
 
 /**
- * Writes `len` bytes from `src` into underlying :c:type:`z_loaned_bytes_t.
+ * Writes `len` bytes from `src` into underlying :c:type:`z_loaned_bytes_t`.
  *
  * Parameters:
  *   writer: A data writer.
@@ -815,7 +819,7 @@ z_result_t z_bytes_writer_write_all(z_loaned_bytes_writer_t *writer, const uint8
  *   bytes: A data to append.
  *
  * Return:
- *   ``0`` in case of success, negative error code otherwise
+ *   ``0`` if write is successful, ``negative value`` otherwise.
  */
 z_result_t z_bytes_writer_append(z_loaned_bytes_writer_t *writer, z_moved_bytes_t *bytes);