diff --git a/docs/api.rst b/docs/api.rst index 519e640fd..66f39c61c 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -150,7 +150,7 @@ Common Key expression -------------- -Represents a key expression in Zenoh. +Represents a `key expression `_ in Zenoh. Types ^^^^^ @@ -399,7 +399,7 @@ A closure is a structure that contains all the elements for stateful, memory-lea - call: the typical callback function. ``context`` will be passed as its last argument. - drop: allows the callback's state to be freed. ``context`` will be passed as its last argument. -Closures are not guaranteed not to be called concurrently. +There is no guarantee closures won't be called concurrently. It is guaranteed that: - ``call`` will never be called once ``drop`` has started. diff --git a/docs/concepts.rst b/docs/concepts.rst index 3458539f2..0df3b88b4 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -160,4 +160,4 @@ Name Prefixes `z_`, `zp_` Most functions and types in the C API use the `z_` prefix, which applies to the common zenoh C API (currently Rust-based zenoh-c and pure C zenoh-pico). -The `zp_` prefix is specific to zenoh-pico. zenoh-c uses the `zc_` prefix for the same purpose. +The `zp_` prefix is used for functions that are exclusive to zenoh-pico, zenoh-c uses the `zc_` prefix for the same purpose. diff --git a/docs/index.rst b/docs/index.rst index f00e1c2cf..d9d4dd76c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,7 @@ zenoh-pico ********** -The *libzenoh-pico* library provides a C client API for the zenoh protocol. +The *libzenoh-pico* library provides a C client API for the `Zenoh protocol `_. .. toctree:: :maxdepth: 10 diff --git a/include/zenoh-pico/api/constants.h b/include/zenoh-pico/api/constants.h index c89bae4cb..2ef89503a 100644 --- a/include/zenoh-pico/api/constants.h +++ b/include/zenoh-pico/api/constants.h @@ -87,11 +87,11 @@ typedef enum { * Intersection level of two key expressions. * * Enumerators: - * Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT: two key expressions do not intersect. - * Z_KEYEXPR_INTERSECTION_LEVEL_INTERSECTS: two key expressions intersect, i.e. there exists at least one key + * Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT: The two key expressions do not intersect. + * Z_KEYEXPR_INTERSECTION_LEVEL_INTERSECTS: The two key expressions intersect, i.e. there exists at least one key * expression that is included by both. - * Z_KEYEXPR_INTERSECTION_LEVEL_INCLUDES: First key expression is the superset of the second one. - * Z_KEYEXPR_INTERSECTION_LEVEL_EQUALS: two key expressions are equal. + * Z_KEYEXPR_INTERSECTION_LEVEL_INCLUDES: The first key expression is the superset of the second one. + * Z_KEYEXPR_INTERSECTION_LEVEL_EQUALS: The two key expressions are equal. */ typedef enum { Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT = 0, diff --git a/include/zenoh-pico/api/primitives.h b/include/zenoh-pico/api/primitives.h index f56037360..038aeafad 100644 --- a/include/zenoh-pico/api/primitives.h +++ b/include/zenoh-pico/api/primitives.h @@ -66,8 +66,8 @@ z_result_t z_view_string_from_substr(z_view_string_t *str, const char *value, si * This function will fail if the string is not in canon form. * * Parameters: - * name: Pointer to string representation of the keyexpr as a null terminated string. * keyexpr: Pointer to an uninitialized :c:type:`z_view_keyexpr_t`. + * name: Pointer to string representation of the keyexpr as a null terminated string. * * Return: * ``0`` if creation successful, ``negative value`` otherwise. @@ -159,7 +159,6 @@ z_result_t z_keyexpr_as_view_string(const z_loaned_keyexpr_t *keyexpr, z_view_st /** * Constructs key expression by concatenation of key expression in `left` with a string in `right`. - * Returns 0 in case of success, negative error code otherwise. * * To avoid odd behaviors, concatenating a key expression starting with `*` to one ending with `*` is forbidden by this * operation, as this would extremely likely cause bugs. @@ -446,8 +445,8 @@ z_result_t z_slice_copy_from_buf(z_owned_slice_t *slice, const uint8_t *data, si * slice: Pointer to an uninitialized :c:type:`z_owned_slice_t`. * data: Pointer to the data to be owned by `slice`. * len: Number of bytes in `data`. - * deleter: A thread-safe delete function to free the `data`. Will be called once when the `slice` is dropped. - * Can be NULL, in case if a `data` is allocated in static memory. + * deleter: A thread-safe delete function to free the `data`. Will be called once when `slice` is dropped. + * Can be NULL in the case where `data` is allocated in static memory. * context: An optional context to be passed to the `deleter`. * * Return: @@ -473,7 +472,7 @@ z_result_t z_view_slice_from_buf(z_view_slice_t *slice, uint8_t *data, size_t le * Builds an empty :c:type:`z_owned_slice_t`. * * Parameters: - * str: Pointer to an uninitialized :c:type:`z_owned_slice_t`. + * slice: Pointer to an uninitialized :c:type:`z_owned_slice_t`. */ void z_slice_empty(z_owned_slice_t *slice); @@ -503,7 +502,7 @@ size_t z_slice_len(const z_loaned_slice_t *slice); * Checks if slice is empty * * Parameters: - * str: Pointer to a :c:type:`z_loaned_slice_t` to check. + * slice: Pointer to a :c:type:`z_loaned_slice_t` to check. * * Return: * ``true`` if the container is empty, ``false`` otherwise. @@ -565,8 +564,8 @@ z_result_t z_bytes_copy_from_slice(z_owned_bytes_t *bytes, const z_loaned_slice_ * bytes: An uninitialized :c:type:`z_owned_bytes_t` to contain the encoded data. * data: Pointer to the data to convert. Ownership is transferred to the `bytes`. * len: Number of bytes to consider. - * deleter: A thread-safe delete function to free the `data`. Will be called once when `bytes` is dropped. Can be - * NULL, in case if a `data` is allocated in static memory. + * deleter: A thread-safe delete function to free the `data`. Will be called once when `bytes` is dropped. + * Can be NULL in the case where `data` is allocated in static memory. * context: An optional context to be passed to the `deleter`. * * Return: @@ -631,9 +630,9 @@ z_result_t z_bytes_copy_from_string(z_owned_bytes_t *bytes, const z_loaned_strin * Parameters: * bytes: An uninitialized :c:type:`z_owned_bytes_t` to contain the encoded string. * value: Pointer to the string to converts. Ownership is transferred to the `bytes`. - * deleter: A thread-safe delete function to free the `value`. Will be called once when `bytes` is dropped. Can be - * NULL, in case if a `value` is allocated in static memory. context: An optional context to be passed to the - * `deleter`. context: An optional context to be passed to the `deleter`. + * deleter: A thread-safe delete function to free the `value`. Will be called once when `bytes` is dropped. + * Can be NULL in the case where `value` is allocated in static memory. + * context: An optional context to be passed to the `deleter`. * * Return: * ``0`` if conversion is successful, ``negative value`` otherwise. @@ -1190,8 +1189,8 @@ z_result_t z_string_copy_from_str(z_owned_string_t *str, const char *value); * Parameters: * str: Pointer to an uninitialized :c:type:`z_owned_string_t`. * value: Pointer to a null terminated string to be owned by `str`. - * deleter: A thread-safe delete function to free the `value`. Will be called once when `str` is dropped. Can be - * NULL, in case if a `value` is allocated in static memory. + * deleter: A thread-safe delete function to free the `value`. Will be called once when `str` is dropped. + * Can be NULL in the case where `value` is allocated in static memory. * context: An optional context to be passed to the `deleter`. * * Return: @@ -1901,9 +1900,9 @@ z_result_t z_keyexpr_from_str_autocanonize(z_owned_keyexpr_t *keyexpr, const cha * * Parameters: * keyexpr: Pointer to an uninitialized :c:type:`z_owned_keyexpr_t` to store the keyexpr. - * name: Pointer to the start of the substring for keyxpr. + * name: Pointer to the start of the substring for keyexpr. * len: Length of the substring to consider. After the function return it will be equal to the canonized key - * expression string length. + * expression string length. * * Return: * ``0`` if creation is successful, ``negative value`` otherwise.