From 2cb1bd8c7d27ca792eb6f47753d9a7258fa4636d Mon Sep 17 00:00:00 2001 From: Alexander Bushnev Date: Fri, 4 Oct 2024 22:30:06 +0200 Subject: [PATCH] Syntax and formatting fixes --- include/zenoh-pico/api/constants.h | 97 +++++++++--------- include/zenoh-pico/api/encoding.h | 6 +- include/zenoh-pico/api/primitives.h | 132 ++++++++++++------------- include/zenoh-pico/api/serialization.h | 4 +- include/zenoh-pico/api/types.h | 22 ++--- 5 files changed, 131 insertions(+), 130 deletions(-) diff --git a/include/zenoh-pico/api/constants.h b/include/zenoh-pico/api/constants.h index 027879f44..c89bae4cb 100644 --- a/include/zenoh-pico/api/constants.h +++ b/include/zenoh-pico/api/constants.h @@ -25,9 +25,9 @@ extern "C" { * What bitmask for scouting. * * Enumerators: - * Z_WHAT_ROUTER: Router. - * Z_WHAT_PEER: Peer. - * Z_WHAT_CLIENT: Client. + * Z_WHAT_ROUTER: Router. + * Z_WHAT_PEER: Peer. + * Z_WHAT_CLIENT: Client. */ typedef enum { Z_WHAT_ROUTER = 0x01, // Router @@ -43,9 +43,9 @@ typedef enum { * Whatami values, defined as a bitmask. * * Enumerators: - * Z_WHATAMI_ROUTER: Bitmask to filter Zenoh routers. - * Z_WHATAMI_PEER: Bitmask to filter for Zenoh peers. - * Z_WHATAMI_CLIENT: Bitmask to filter for Zenoh clients. + * Z_WHATAMI_ROUTER: Bitmask to filter Zenoh routers. + * Z_WHATAMI_PEER: Bitmask to filter for Zenoh peers. + * Z_WHATAMI_CLIENT: Bitmask to filter for Zenoh clients. */ typedef enum z_whatami_t { Z_WHATAMI_ROUTER = 0x01, @@ -60,16 +60,16 @@ typedef enum z_whatami_t { * like :c:func:`z_keyexpr_is_canon` or :c:func:`z_keyexpr_canonize`. * * Enumerators: - * Z_KEYEXPR_CANON_SUCCESS: The key expression is canon. - * Z_KEYEXPR_CANON_LONE_DOLLAR_STAR: The key contains a ``$*`` chunk, which must be replaced by ``*``. - * Z_KEYEXPR_CANON_SINGLE_STAR_AFTER_DOUBLE_STAR: The key contains ``** / *``, which must be replaced by ``* / **``. - * Z_KEYEXPR_CANON_DOUBLE_STAR_AFTER_DOUBLE_STAR: The key contains ``** / **``, which must be replaced by ``**``. - * Z_KEYEXPR_CANON_EMPTY_CHUNK: The key contains empty chunks. - * Z_KEYEXPR_CANON_STARS_IN_CHUNK: The key contains a ``*`` in a chunk without being escaped by a DSL, which is - * forbidden. - * Z_KEYEXPR_CANON_DOLLAR_AFTER_DOLLAR_OR_STAR: The key contains ``$*$`` or ``$$``, which is forbidden. - * Z_KEYEXPR_CANON_CONTAINS_SHARP_OR_QMARK: The key contains ``#`` or ``?``, which is forbidden. - * Z_KEYEXPR_CANON_CONTAINS_UNBOUND_DOLLAR: The key contains a ``$`` which is not bound to a DSL. + * Z_KEYEXPR_CANON_SUCCESS: The key expression is canon. + * Z_KEYEXPR_CANON_LONE_DOLLAR_STAR: The key contains a ``$*`` chunk, which must be replaced by ``*``. + * Z_KEYEXPR_CANON_SINGLE_STAR_AFTER_DOUBLE_STAR: The key contains ``** / *``, which must be replaced by ``* / **``. + * Z_KEYEXPR_CANON_DOUBLE_STAR_AFTER_DOUBLE_STAR: The key contains ``** / **``, which must be replaced by ``**``. + * Z_KEYEXPR_CANON_EMPTY_CHUNK: The key contains empty chunks. + * Z_KEYEXPR_CANON_STARS_IN_CHUNK: The key contains a ``*`` in a chunk without being escaped by a DSL, which is + * forbidden. + * Z_KEYEXPR_CANON_DOLLAR_AFTER_DOLLAR_OR_STAR: The key contains ``$*$`` or ``$$``, which is forbidden. + * Z_KEYEXPR_CANON_CONTAINS_SHARP_OR_QMARK: The key contains ``#`` or ``?``, which is forbidden. + * Z_KEYEXPR_CANON_CONTAINS_UNBOUND_DOLLAR: The key contains a ``$`` which is not bound to a DSL. */ typedef enum { Z_KEYEXPR_CANON_SUCCESS = 0, @@ -84,13 +84,14 @@ typedef enum { } zp_keyexpr_canon_status_t; /** - * Intersection level of 2 key expressions. + * Intersection level of two key expressions. * * Enumerators: - * Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT: 2 key expression do not intersect. - * Z_KEYEXPR_INTERSECTION_LEVEL_INTERSECTS: 2 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 second one. - * Z_KEYEXPR_INTERSECTION_LEVEL_EQUALS: 2 key expressions are equal. + * 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 + * 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. */ typedef enum { Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT = 0, @@ -103,8 +104,8 @@ typedef enum { * Sample kind values. * * Enumerators: - * Z_SAMPLE_KIND_PUT: The Sample was issued by a ``put`` operation. - * Z_SAMPLE_KIND_DELETE: The Sample was issued by a ``delete`` operation. + * Z_SAMPLE_KIND_PUT: The Sample was issued by a ``put`` operation. + * Z_SAMPLE_KIND_DELETE: The Sample was issued by a ``delete`` operation. */ typedef enum { Z_SAMPLE_KIND_PUT = 0, Z_SAMPLE_KIND_DELETE = 1 } z_sample_kind_t; #define Z_SAMPLE_KIND_DEFAULT Z_SAMPLE_KIND_PUT @@ -113,14 +114,14 @@ typedef enum { Z_SAMPLE_KIND_PUT = 0, Z_SAMPLE_KIND_DELETE = 1 } z_sample_kind_t * Consolidation mode values. * * Enumerators: - * Z_CONSOLIDATION_MODE_AUTO: Let Zenoh decide the best consolidation mode depending on the query selector. - * Z_CONSOLIDATION_MODE_NONE: No consolidation is applied. Replies may come in any order and any number. - * Z_CONSOLIDATION_MODE_MONOTONIC: It guarantees that any reply for a given key expression will be monotonic in time - * w.r.t. the previous received replies for the same key expression. I.e., for the same key expression multiple - * replies may be received. It is guaranteed that two replies received at t1 and t2 will have timestamp - * ts2 > ts1. It optimizes latency. - * Z_CONSOLIDATION_MODE_LATEST: It guarantees unicity of replies for the same key expression. - * It optimizes bandwidth. + * Z_CONSOLIDATION_MODE_AUTO: Let Zenoh decide the best consolidation mode depending on the query selector. + * Z_CONSOLIDATION_MODE_NONE: No consolidation is applied. Replies may come in any order and any number. + * Z_CONSOLIDATION_MODE_MONOTONIC: It guarantees that any reply for a given key expression will be monotonic in time + * w.r.t. the previous received replies for the same key expression. I.e., for the same key expression multiple + * replies may be received. It is guaranteed that two replies received at t1 and t2 will have timestamp + * ts2 > ts1. It optimizes latency. + * Z_CONSOLIDATION_MODE_LATEST: It guarantees unicity of replies for the same key expression. + * It optimizes bandwidth. */ typedef enum { Z_CONSOLIDATION_MODE_AUTO = -1, @@ -134,8 +135,8 @@ typedef enum { * Reliability values. * * Enumerators: - * Z_RELIABILITY_BEST_EFFORT: Defines reliability as ``BEST_EFFORT`` - * Z_RELIABILITY_RELIABLE: Defines reliability as ``RELIABLE`` + * Z_RELIABILITY_BEST_EFFORT: Defines reliability as ``BEST_EFFORT`` + * Z_RELIABILITY_RELIABLE: Defines reliability as ``RELIABLE`` * * .. warning:: This API has been marked as unstable: it works as advertised, but it may be changed in a future release. */ @@ -146,10 +147,10 @@ typedef enum { Z_RELIABILITY_BEST_EFFORT = 1, Z_RELIABILITY_RELIABLE = 0 } z_rel * Congestion control values. * * Enumerators: - * Z_CONGESTION_CONTROL_BLOCK: Defines congestion control as ``BLOCK``. Messages are not dropped in case of - * congestion control. - * Z_CONGESTION_CONTROL_DROP: Defines congestion control as ``DROP``. Messages are dropped in case - * of congestion control. + * Z_CONGESTION_CONTROL_BLOCK: Defines congestion control as ``BLOCK``. Messages are not dropped in case of + * congestion control. + * Z_CONGESTION_CONTROL_DROP: Defines congestion control as ``DROP``. Messages are dropped in case + * of congestion control. */ typedef enum { Z_CONGESTION_CONTROL_BLOCK = 0, Z_CONGESTION_CONTROL_DROP = 1 } z_congestion_control_t; #define Z_CONGESTION_CONTROL_DEFAULT Z_CONGESTION_CONTROL_BLOCK @@ -158,14 +159,14 @@ typedef enum { Z_CONGESTION_CONTROL_BLOCK = 0, Z_CONGESTION_CONTROL_DROP = 1 } z * Priority of Zenoh messages values. * * Enumerators: - * _Z_PRIORITY_CONTROL: Priority for ``Control`` messages. - * Z_PRIORITY_REAL_TIME: Priority for ``RealTime`` messages. - * Z_PRIORITY_INTERACTIVE_HIGH: Highest priority for ``Interactive`` messages. - * Z_PRIORITY_INTERACTIVE_LOW: Lowest priority for ``Interactive`` messages. - * Z_PRIORITY_DATA_HIGH: Highest priority for ``Data`` messages. - * Z_PRIORITY_DATA: Default priority for ``Data`` messages. - * Z_PRIORITY_DATA_LOW: Lowest priority for ``Data`` messages. - * Z_PRIORITY_BACKGROUND: Priority for ``Background traffic`` messages. + * _Z_PRIORITY_CONTROL: Priority for ``Control`` messages. + * Z_PRIORITY_REAL_TIME: Priority for ``RealTime`` messages. + * Z_PRIORITY_INTERACTIVE_HIGH: Highest priority for ``Interactive`` messages. + * Z_PRIORITY_INTERACTIVE_LOW: Lowest priority for ``Interactive`` messages. + * Z_PRIORITY_DATA_HIGH: Highest priority for ``Data`` messages. + * Z_PRIORITY_DATA: Default priority for ``Data`` messages. + * Z_PRIORITY_DATA_LOW: Lowest priority for ``Data`` messages. + * Z_PRIORITY_BACKGROUND: Priority for ``Background traffic`` messages. */ typedef enum { _Z_PRIORITY_CONTROL = 0, @@ -183,9 +184,9 @@ typedef enum { * Query target values. * * Enumerators: - * Z_QUERY_TARGET_BEST_MATCHING: The nearest complete queryable if any else all matching queryables. - * Z_QUERY_TARGET_ALL: All matching queryables. - * Z_QUERY_TARGET_ALL_COMPLETE: A set of complete queryables. + * Z_QUERY_TARGET_BEST_MATCHING: The nearest complete queryable if any else all matching queryables. + * Z_QUERY_TARGET_ALL: All matching queryables. + * Z_QUERY_TARGET_ALL_COMPLETE: A set of complete queryables. */ typedef enum { Z_QUERY_TARGET_BEST_MATCHING = 0, diff --git a/include/zenoh-pico/api/encoding.h b/include/zenoh-pico/api/encoding.h index e7df22dfe..69fe9f1ff 100644 --- a/include/zenoh-pico/api/encoding.h +++ b/include/zenoh-pico/api/encoding.h @@ -247,7 +247,7 @@ const z_loaned_encoding_t *z_encoding_text_json5(void); extern const z_owned_encoding_t ENCODING_TEXT_JSON5; /** - * A Python object serialized using [pickle](https://docs.python.org/3/library/pickle.html). + * A Python object serialized using `pickle `_. * Constant alias for string: `"application/python-serialized-object"`. */ const z_loaned_encoding_t *z_encoding_application_python_serialized_object(void); @@ -268,8 +268,8 @@ const z_loaned_encoding_t *z_encoding_application_java_serialized_object(void); extern const z_owned_encoding_t ENCODING_APPLICATION_JAVA_SERIALIZED_OBJECT; /** - * An [openmetrics](https://github.com/OpenObservability/OpenMetrics) data, commonly used by - * [Prometheus](https://prometheus.io/). + * An `openmetrics `_ data, commonly used by + * `Prometheus `_. * Constant alias for string: `"application/openmetrics-text"`. */ const z_loaned_encoding_t *z_encoding_application_openmetrics_text(void); diff --git a/include/zenoh-pico/api/primitives.h b/include/zenoh-pico/api/primitives.h index 28dc76012..f56037360 100644 --- a/include/zenoh-pico/api/primitives.h +++ b/include/zenoh-pico/api/primitives.h @@ -181,8 +181,8 @@ z_result_t z_keyexpr_concat(z_owned_keyexpr_t *key, const z_loaned_keyexpr_t *le * * Parameters: * keyexpr: Pointer to an uninitialized :c:type:`z_owned_keyexpr_t` to store the keyexpr. - * left: Pointer to :c:type:`z_loaned_keyexpr_t` to the left part of resulting key expression. - * right: Pointer to :c:type:`z_loaned_keyexpr_t` to the right part of resulting key expression. + * left: Pointer to :c:type:`z_loaned_keyexpr_t` to the left part of the resulting key expression. + * right: Pointer to :c:type:`z_loaned_keyexpr_t` to the right part of the resulting key expression. * * Return: * ``0`` if creation successful, ``negative value`` otherwise. @@ -190,7 +190,7 @@ z_result_t z_keyexpr_concat(z_owned_keyexpr_t *key, const z_loaned_keyexpr_t *le z_result_t z_keyexpr_join(z_owned_keyexpr_t *key, const z_loaned_keyexpr_t *left, const z_loaned_keyexpr_t *right); /** - * Returns the relation between `left` and `right` from `left`'s point of view. + * Returns the relation between `left` and `right` from the `left`'s point of view. * * Note that this is slower than `z_keyexpr_intersects` and `keyexpr_includes`, so you should favor these methods for * most applications. @@ -200,7 +200,7 @@ z_result_t z_keyexpr_join(z_owned_keyexpr_t *key, const z_loaned_keyexpr_t *left * right: Pointer to :c:type:`z_loaned_keyexpr_t` representing right key expression. * * Return: - * Relation between `left` and `right` from `left`'s point of view. + * Relation between `left` and `right` from the `left`'s point of view. */ z_keyexpr_intersection_level_t z_keyexpr_relation_to(const z_loaned_keyexpr_t *left, const z_loaned_keyexpr_t *right); @@ -212,7 +212,7 @@ z_keyexpr_intersection_level_t z_keyexpr_relation_to(const z_loaned_keyexpr_t *l * len: Number of characters in ``start``. * * Return: - * ``0`` if passed string is a valid (and canon) key expression, or a ``negative value`` otherwise. + * ``0`` if the passed string is a valid (and canon) key expression, or a ``negative value`` otherwise. * Error codes are defined in :c:enum:`zp_keyexpr_canon_status_t`. */ z_result_t z_keyexpr_is_canon(const char *start, size_t len); @@ -253,7 +253,7 @@ z_result_t z_keyexpr_canonize_null_terminated(char *start); * * Return: * ``true`` if ``l`` includes ``r``, i.e. the set defined by ``l`` contains every key belonging to the set - * defined by ``r``. Otherwise, returns ``false``. + * defined by ``r``. Otherwise, returns ``false``. */ bool z_keyexpr_includes(const z_loaned_keyexpr_t *l, const z_loaned_keyexpr_t *r); @@ -266,7 +266,7 @@ bool z_keyexpr_includes(const z_loaned_keyexpr_t *l, const z_loaned_keyexpr_t *r * * Return: * ``true`` if keyexprs intersect, i.e. there exists at least one key which is contained in both of the - * sets defined by ``l`` and ``r``. Otherwise, returns ``false``. + * sets defined by ``l`` and ``r``. Otherwise, returns ``false``. */ bool z_keyexpr_intersects(const z_loaned_keyexpr_t *l, const z_loaned_keyexpr_t *r); @@ -299,7 +299,7 @@ void z_config_new(z_owned_config_t *config); * config: Pointer to uninitialized :c:type:`z_owned_config_t`. * * Return: - * `0`` in case of success, or a ``negative value`` otherwise. + * ``0`` in case of success, or a ``negative value`` otherwise. */ z_result_t z_config_default(z_owned_config_t *config); @@ -324,7 +324,7 @@ const char *zp_config_get(const z_loaned_config_t *config, uint8_t key); * value: Property value to be inserted. * * Return: - * ``0`` if insertion successful, ``negative value`` otherwise. + * ``0`` if insertion is successful, ``negative value`` otherwise. */ z_result_t zp_config_insert(z_loaned_config_t *config, uint8_t key, const char *value); @@ -336,7 +336,7 @@ z_result_t zp_config_insert(z_loaned_config_t *config, uint8_t key, const char * * s: Pointer to the null terminated string to use. * * Return: - * ``0`` if creation successful,``negative value`` otherwise. + * ``0`` if creation is successful,``negative value`` otherwise. */ z_result_t z_encoding_from_str(z_owned_encoding_t *encoding, const char *s); @@ -349,7 +349,7 @@ z_result_t z_encoding_from_str(z_owned_encoding_t *encoding, const char *s); * len: Number of characters from the string s to use. * * Return: - * ``0`` if creation successful,``negative value`` otherwise. + * ``0`` if creation is successful,``negative value`` otherwise. */ z_result_t z_encoding_from_substr(z_owned_encoding_t *encoding, const char *s, size_t len); @@ -388,7 +388,7 @@ z_result_t z_encoding_set_schema_from_substr(z_loaned_encoding_t *encoding, cons * string: Pointer to an uninitialized :c:type:`z_owned_string_t` to store the string. * * Return: - * ``0`` if creation successful,``negative value`` otherwise. + * ``0`` if creation is successful,``negative value`` otherwise. */ z_result_t z_encoding_to_string(const z_loaned_encoding_t *encoding, z_owned_string_t *string); @@ -435,7 +435,7 @@ const z_loaned_encoding_t *z_reply_err_encoding(const z_loaned_reply_err_t *repl * len: Number of bytes to copy. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_slice_copy_from_buf(z_owned_slice_t *slice, const uint8_t *data, size_t len); @@ -446,12 +446,12 @@ 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 `slice` is dropped. Can be - * NULL, in case if `data` is allocated in static memory. + * 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. * context: An optional context to be passed to the `deleter`. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_slice_from_buf(z_owned_slice_t *slice, uint8_t *data, size_t len, void (*deleter)(void *data, void *context), void *context); @@ -465,7 +465,7 @@ z_result_t z_slice_from_buf(z_owned_slice_t *slice, uint8_t *data, size_t len, * len: Number of bytes in `data`. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_view_slice_from_buf(z_view_slice_t *slice, uint8_t *data, size_t len); @@ -489,7 +489,7 @@ void z_slice_empty(z_owned_slice_t *slice); const uint8_t *z_slice_data(const z_loaned_slice_t *slice); /** - * Gets total number of bytes in a bytes array. + * Gets the total number of bytes in a bytes array. * * Parameters: * slice: Pointer to a :c:type:`z_loaned_slice_t` to get length from. @@ -506,7 +506,7 @@ size_t z_slice_len(const z_loaned_slice_t *slice); * str: Pointer to a :c:type:`z_loaned_slice_t` to check. * * Return: - * ``true`` if conainer is empty, ``false`` otherwise. + * ``true`` if the container is empty, ``false`` otherwise. */ bool z_slice_is_empty(const z_loaned_slice_t *slice); @@ -518,7 +518,7 @@ bool z_slice_is_empty(const z_loaned_slice_t *slice); * dst: Pointer to an uninitialized :c:type:`z_owned_slice_t` to contain the decoded slice. * * Return: - * ``0`` if decode successful, or a ``negative value`` otherwise. + * ``0`` if decode is successful, or a ``negative value`` otherwise. */ z_result_t z_bytes_to_slice(const z_loaned_bytes_t *bytes, z_owned_slice_t *dst); @@ -530,7 +530,7 @@ z_result_t z_bytes_to_slice(const z_loaned_bytes_t *bytes, z_owned_slice_t *dst) * str: Pointer to an uninitialized :c:type:`z_owned_string_t` to contain the decoded string. * * Return: - * ``0`` if decode successful, or a ``negative value`` otherwise. + * ``0`` if decode is successful, or a ``negative value`` otherwise. */ z_result_t z_bytes_to_string(const z_loaned_bytes_t *bytes, z_owned_string_t *str); @@ -566,7 +566,7 @@ z_result_t z_bytes_copy_from_slice(z_owned_bytes_t *bytes, const z_loaned_slice_ * 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 `data` is allocated in static memory. + * NULL, in case if a `data` is allocated in static memory. * context: An optional context to be passed to the `deleter`. * * Return: @@ -632,8 +632,8 @@ z_result_t z_bytes_copy_from_string(z_owned_bytes_t *bytes, const z_loaned_strin * 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 `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`. + * 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`. * * Return: * ``0`` if conversion is successful, ``negative value`` otherwise. @@ -837,7 +837,7 @@ z_result_t z_bytes_writer_append(z_loaned_bytes_writer_t *writer, z_moved_bytes_ * zs: Pointer to a :c:type:`z_loaned_session_t` to get the id from. * * Return: - * ``0`` if encode successful, ``negative value`` otherwise (for example if RTC is not available on the system). + * ``0`` if encode is successful, ``negative value`` otherwise (for example if RTC is not available on the system). */ z_result_t z_timestamp_new(z_timestamp_t *ts, const z_loaned_session_t *zs); @@ -870,7 +870,7 @@ z_id_t z_timestamp_id(const z_timestamp_t *ts); * ts: Timestamp value to check validity of. * * Return: - * ``true`` if timestamp is valid, ``false`` otherwise. + * ``true`` if the timestamp is valid, ``false`` otherwise. */ bool z_timestamp_check(z_timestamp_t ts); @@ -1180,7 +1180,7 @@ size_t z_string_len(const z_loaned_string_t *str); * value: Pointer to a null terminated string to be copied. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_string_copy_from_str(z_owned_string_t *str, const char *value); @@ -1191,11 +1191,11 @@ z_result_t z_string_copy_from_str(z_owned_string_t *str, const char *value); * 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 `value` is allocated in static memory. + * NULL, in case if a `value` is allocated in static memory. * context: An optional context to be passed to the `deleter`. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_string_from_str(z_owned_string_t *str, char *value, void (*deleter)(void *value, void *context), void *context); @@ -1217,7 +1217,7 @@ void z_string_empty(z_owned_string_t *str); * len: String size. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_string_copy_from_substr(z_owned_string_t *str, const char *value, size_t len); @@ -1228,7 +1228,7 @@ z_result_t z_string_copy_from_substr(z_owned_string_t *str, const char *value, s * str: Pointer to a :c:type:`z_loaned_string_t` to check. * * Return: - * ``true`` if conainer is empty, ``false`` otherwise. + * ``true`` if the string is empty, ``false`` otherwise. */ bool z_string_is_empty(const z_loaned_string_t *str); @@ -1236,7 +1236,7 @@ bool z_string_is_empty(const z_loaned_string_t *str); * Returns :c:type:`z_loaned_slice_t` for the string * * Parameters: - * str: Pointer to a :c:type:`z_loaned_string_t` to get slice. + * str: Pointer to a :c:type:`z_loaned_string_t` to get a slice. * * Return: * slice containing string data @@ -1317,7 +1317,7 @@ z_result_t z_whatami_to_view_string(z_whatami_t whatami, z_view_string_t *str_ou * options: Pointer to a :c:type:`z_scout_options_t` to configure the operation. * * Return: - * ``0`` if scouting successfully triggered, ``negative value`` otherwise. + * ``0`` if scouting was successfully triggered, ``negative value`` otherwise. */ z_result_t z_scout(z_moved_config_t *config, z_moved_closure_hello_t *callback, const z_scout_options_t *options); @@ -1330,7 +1330,7 @@ z_result_t z_scout(z_moved_config_t *config, z_moved_closure_hello_t *callback, * options: Pointer to a :c:type:`z_open_options_t` to configure the operation. * * Return: - * ``0`` if open successful, ``negative value`` otherwise. + * ``0`` if open is successful, ``negative value`` otherwise. */ z_result_t z_open(z_owned_session_t *zs, z_moved_config_t *config, const z_open_options_t *options); @@ -1342,7 +1342,7 @@ z_result_t z_open(z_owned_session_t *zs, z_moved_config_t *config, const z_open_ * options: Pointer to a :c:type:`z_close_options_t` to configure the operation. * * Return: - * ``0`` if close successful, ``negative value`` otherwise. + * ``0`` if close is successful, ``negative value`` otherwise. */ z_result_t z_close(z_loaned_session_t *zs, const z_close_options_t *options); @@ -1368,7 +1368,7 @@ bool z_session_is_closed(const z_loaned_session_t *zs); * callback: Moved :c:type:`z_owned_closure_zid_t` callback. * * Return: - * ``0`` if operation successfully triggered, ``negative value`` otherwise. + * ``0`` if operation was successfully triggered, ``negative value`` otherwise. */ z_result_t z_info_peers_zid(const z_loaned_session_t *zs, z_moved_closure_zid_t *callback); @@ -1383,7 +1383,7 @@ z_result_t z_info_peers_zid(const z_loaned_session_t *zs, z_moved_closure_zid_t * callback: Moved :c:type:`z_owned_closure_zid_t` callback. * * Return: - * ``0`` if operation successfully triggered, ``negative value`` otherwise. + * ``0`` if operation was successfully triggered, ``negative value`` otherwise. */ z_result_t z_info_routers_zid(const z_loaned_session_t *zs, z_moved_closure_zid_t *callback); @@ -1408,7 +1408,7 @@ z_id_t z_info_zid(const z_loaned_session_t *zs); * str: Pointer to uninitialized :c:type:`z_owned_string_t` to store the string. * * Return: - * ``0`` if operation successful, ``negative value`` otherwise. + * ``0`` if operation is successful, ``negative value`` otherwise. */ z_result_t z_id_to_string(const z_id_t *id, z_owned_string_t *str); @@ -1483,7 +1483,7 @@ z_reliability_t z_sample_reliability(const z_loaned_sample_t *sample); #endif /** - * Got sample qos congestion control value. + * Got a sample qos congestion control value. * * Parameters: * sample: Pointer to a :c:type:`z_loaned_sample_t` to get the congestion control from. @@ -1531,7 +1531,7 @@ const z_loaned_bytes_t *z_sample_attachment(const z_loaned_sample_t *sample); * Builds a :c:type:`z_put_options_t` with default values. * * Parameters: - * Pointer to an uninitialized :c:type:`z_put_options_t`. + * options: Pointer to an uninitialized :c:type:`z_put_options_t`. */ void z_put_options_default(z_put_options_t *options); @@ -1539,7 +1539,7 @@ void z_put_options_default(z_put_options_t *options); * Builds a :c:type:`z_delete_options_t` with default values. * * Parameters: - * Pointer to an uninitialized :c:type:`z_delete_options_t`. + * options: Pointer to an uninitialized :c:type:`z_delete_options_t`. */ void z_delete_options_default(z_delete_options_t *options); @@ -1553,7 +1553,7 @@ void z_delete_options_default(z_delete_options_t *options); * options: Pointer to a :c:type:`z_put_options_t` to configure the operation. * * Return: - * ``0`` if put operation successful, ``negative value`` otherwise. + * ``0`` if put operation is successful, ``negative value`` otherwise. */ z_result_t z_put(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_bytes_t *payload, const z_put_options_t *options); @@ -1567,7 +1567,7 @@ z_result_t z_put(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr * options: Pointer to a :c:type:`z_delete_options_t` to configure the operation. * * Return: - * ``0`` if delete operation successful, ``negative value`` otherwise. + * ``0`` if delete operation is successful, ``negative value`` otherwise. */ z_result_t z_delete(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, const z_delete_options_t *options); @@ -1575,7 +1575,7 @@ z_result_t z_delete(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keye * Builds a :c:type:`z_publisher_options_t` with default values. * * Parameters: - * Pointer to an uninitialized :c:type:`z_delete_options_t`. + * options: Pointer to an uninitialized :c:type:`z_delete_options_t`. */ void z_publisher_options_default(z_publisher_options_t *options); @@ -1592,7 +1592,7 @@ void z_publisher_options_default(z_publisher_options_t *options); * options: Pointer to a :c:type:`z_publisher_options_t` to configure the operation. * * Return: - * ``0`` if declare successful, ``negative value`` otherwise. + * ``0`` if declare is successful, ``negative value`` otherwise. */ z_result_t z_declare_publisher(z_owned_publisher_t *pub, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, const z_publisher_options_t *options); @@ -1604,7 +1604,7 @@ z_result_t z_declare_publisher(z_owned_publisher_t *pub, const z_loaned_session_ * pub: Moved :c:type:`z_owned_publisher_t` to undeclare. * * Return: - * ``0`` if undeclare successful, ``negative value`` otherwise. + * ``0`` if undeclare is successful, ``negative value`` otherwise. */ z_result_t z_undeclare_publisher(z_moved_publisher_t *pub); @@ -1633,7 +1633,7 @@ void z_publisher_delete_options_default(z_publisher_delete_options_t *options); * options: Pointer to a :c:type:`z_publisher_put_options_t` to configure the operation. * * Return: - * ``0`` if put operation successful, ``negative value`` otherwise. + * ``0`` if put operation is successful, ``negative value`` otherwise. */ z_result_t z_publisher_put(const z_loaned_publisher_t *pub, z_moved_bytes_t *payload, const z_publisher_put_options_t *options); @@ -1646,7 +1646,7 @@ z_result_t z_publisher_put(const z_loaned_publisher_t *pub, z_moved_bytes_t *pay * options: Pointer to a :c:type:`z_publisher_delete_options_t` to configure the delete operation. * * Return: - * ``0`` if delete operation successful, ``negative value`` otherwise. + * ``0`` if delete operation is successful, ``negative value`` otherwise. */ z_result_t z_publisher_delete(const z_loaned_publisher_t *pub, const z_publisher_delete_options_t *options); @@ -1682,7 +1682,7 @@ void z_get_options_default(z_get_options_t *options); * options: Pointer to a :c:type:`z_get_options_t` to configure the operation. * * Return: - * ``0`` if put operation successful, ``negative value`` otherwise. + * ``0`` if put operation is successful, ``negative value`` otherwise. */ z_result_t z_get(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, const char *parameters, z_moved_closure_reply_t *callback, z_get_options_t *options); @@ -1758,7 +1758,7 @@ void z_queryable_options_default(z_queryable_options_t *options); * options: Pointer to a :c:type:`z_queryable_options_t` to configure the declare. * * Return: - * ``0`` if declare operation successful, ``negative value`` otherwise. + * ``0`` if declare operation is successful, ``negative value`` otherwise. */ z_result_t z_declare_queryable(z_owned_queryable_t *queryable, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_closure_query_t *callback, @@ -1771,7 +1771,7 @@ z_result_t z_declare_queryable(z_owned_queryable_t *queryable, const z_loaned_se * queryable: Moved :c:type:`z_owned_queryable_t` to undeclare. * * Return: - * ``0`` if undeclare operation successful, ``negative value`` otherwise. + * ``0`` if undeclare operation is successful, ``negative value`` otherwise. */ z_result_t z_undeclare_queryable(z_moved_queryable_t *queryable); @@ -1798,7 +1798,7 @@ void z_query_reply_options_default(z_query_reply_options_t *options); * options: Pointer to a :c:type:`z_query_reply_options_t` to configure the reply. * * Return: - * ``0`` if reply operation successful, ``negative value`` otherwise. + * ``0`` if reply operation is successful, ``negative value`` otherwise. */ z_result_t z_query_reply(const z_loaned_query_t *query, const z_loaned_keyexpr_t *keyexpr, z_moved_bytes_t *payload, const z_query_reply_options_t *options); @@ -1825,7 +1825,7 @@ void z_query_reply_del_options_default(z_query_reply_del_options_t *options); * options: Pointer to a :c:type:`z_query_reply_del_options_t` to configure the reply. * * Return: - * ``0`` if reply operation successful, ``negative value`` otherwise. + * ``0`` if reply operation is successful, ``negative value`` otherwise. */ z_result_t z_query_reply_del(const z_loaned_query_t *query, const z_loaned_keyexpr_t *keyexpr, const z_query_reply_del_options_t *options); @@ -1852,7 +1852,7 @@ void z_query_reply_err_options_default(z_query_reply_err_options_t *options); * options: Pointer to a :c:type:`z_query_reply_err_options_t` to configure the reply error. * * Return: - * ``0`` if reply operation successful, ``negative value`` otherwise. + * ``0`` if reply operation is successful, ``negative value`` otherwise. */ z_result_t z_query_reply_err(const z_loaned_query_t *query, z_moved_bytes_t *payload, const z_query_reply_err_options_t *options); @@ -1867,7 +1867,7 @@ z_result_t z_query_reply_err(const z_loaned_query_t *query, z_moved_bytes_t *pay * name: Pointer to the null-terminated string of the keyexpr. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_keyexpr_from_str(z_owned_keyexpr_t *keyexpr, const char *name); @@ -1880,7 +1880,7 @@ z_result_t z_keyexpr_from_str(z_owned_keyexpr_t *keyexpr, const char *name); * len: Length of the substring to consider. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_keyexpr_from_substr(z_owned_keyexpr_t *keyexpr, const char *name, size_t len); @@ -1892,7 +1892,7 @@ z_result_t z_keyexpr_from_substr(z_owned_keyexpr_t *keyexpr, const char *name, s * name: Pointer to string representation of the keyexpr as a null terminated string. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_keyexpr_from_str_autocanonize(z_owned_keyexpr_t *keyexpr, const char *name); @@ -1906,7 +1906,7 @@ z_result_t z_keyexpr_from_str_autocanonize(z_owned_keyexpr_t *keyexpr, const cha * expression string length. * * Return: - * ``0`` if creation successful, ``negative value`` otherwise. + * ``0`` if creation is successful, ``negative value`` otherwise. */ z_result_t z_keyexpr_from_substr_autocanonize(z_owned_keyexpr_t *keyexpr, const char *name, size_t *len); @@ -1922,7 +1922,7 @@ z_result_t z_keyexpr_from_substr_autocanonize(z_owned_keyexpr_t *keyexpr, const * keyexpr: Pointer to a :c:type:`z_loaned_keyexpr_t` to bind the keyexpr with. * * Return: - * ``0`` if declare successful, ``negative value`` otherwise. + * ``0`` if declare is successful, ``negative value`` otherwise. */ z_result_t z_declare_keyexpr(z_owned_keyexpr_t *declared_keyexpr, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr); @@ -1935,7 +1935,7 @@ z_result_t z_declare_keyexpr(z_owned_keyexpr_t *declared_keyexpr, const z_loaned * zs: Pointer to a :c:type:`z_loaned_session_t` to undeclare the data through. * * Return: - * ``0`` if undeclare successful, ``negative value`` otherwise. + * ``0`` if undeclare is successful, ``negative value`` otherwise. */ z_result_t z_undeclare_keyexpr(z_moved_keyexpr_t *keyexpr, const z_loaned_session_t *zs); @@ -1952,7 +1952,7 @@ void z_string_array_new(z_owned_string_array_t *a); * * Parameters: * a: Pointer to :c:type:`z_loaned_string_array_t`. - * value: Pointer to the string to be add. + * value: Pointer to the string to be added. * * Return: * The new length of the array. @@ -1964,7 +1964,7 @@ size_t z_string_array_push_by_alias(z_loaned_string_array_t *a, const z_loaned_s * * Parameters: * a: Pointer to :c:type:`z_loaned_string_array_t`. - * value: Pointer to the string to be add. + * value: Pointer to the string to be added. * * Return: * The new length of the array. @@ -1984,7 +1984,7 @@ size_t z_string_array_push_by_copy(z_loaned_string_array_t *a, const z_loaned_st const z_loaned_string_t *z_string_array_get(const z_loaned_string_array_t *a, size_t k); /** - * Returns number of elements in the array. + * Returns the number of elements in the array. */ size_t z_string_array_len(const z_loaned_string_array_t *a); @@ -2005,7 +2005,7 @@ void z_subscriber_options_default(z_subscriber_options_t *options); /** * Declares a subscriber for a given keyexpr. * Note that dropping subscriber does not drop its callback, meaning that after subscriber drop the messages will still - * be receieved and processed, until the corresponding session is dropped. To disable the callback with cleanup use + * be received and processed, until the corresponding session is dropped. To disable the callback with cleanup use * :c:func:`z_subscriber_undeclare`. * * Parameters: @@ -2016,7 +2016,7 @@ void z_subscriber_options_default(z_subscriber_options_t *options); * options: Pointer to a :c:type:`z_subscriber_options_t` to configure the operation * * Return: - * ``0`` if declare successful, ``negative value`` otherwise. + * ``0`` if declare is successful, ``negative value`` otherwise. */ z_result_t z_declare_subscriber(z_owned_subscriber_t *sub, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_closure_sample_t *callback, @@ -2029,7 +2029,7 @@ z_result_t z_declare_subscriber(z_owned_subscriber_t *sub, const z_loaned_sessio * sub: Moved :c:type:`z_owned_subscriber_t` to undeclare. * * Return: - * ``0`` if undeclare successful, ``negative value`` otherwise. + * ``0`` if undeclare is successful, ``negative value`` otherwise. */ z_result_t z_undeclare_subscriber(z_moved_subscriber_t *sub); diff --git a/include/zenoh-pico/api/serialization.h b/include/zenoh-pico/api/serialization.h index ca9142dfc..4a2218001 100644 --- a/include/zenoh-pico/api/serialization.h +++ b/include/zenoh-pico/api/serialization.h @@ -524,7 +524,7 @@ z_result_t ze_deserializer_deserialize_string(ze_deserializer_t *deserializer, z * Parameters: * serializer: A serializer instance. * len: Length of the sequence. Could be read during deserialization using - * :c:func:`ze_deserializer_deserialize_sequence_length`. + * :c:func:`ze_deserializer_deserialize_sequence_length`. * * Return: * ``0`` if deserialization is successful, or a ``negative value`` otherwise. @@ -539,7 +539,7 @@ z_result_t ze_serializer_serialize_sequence_length(ze_loaned_serializer_t *seria * Parameters: * deserializer: A deserializer instance. * len: A pointer where the length of the sequence (previously passed via - * :c:func:`ze_serializer_serialize_sequence_length`) will be written. + * :c:func:`ze_serializer_serialize_sequence_length`) will be written. * * Return: * ``0`` if deserialization is successful, or a ``negative value`` otherwise. diff --git a/include/zenoh-pico/api/types.h b/include/zenoh-pico/api/types.h index 152225b3e..7bf8f3eb3 100644 --- a/include/zenoh-pico/api/types.h +++ b/include/zenoh-pico/api/types.h @@ -174,10 +174,10 @@ typedef struct { * Members: * z_owned_encoding_t *encoding: Default encoding for messages put by this publisher. * z_congestion_control_t congestion_control: The congestion control to apply when routing messages from this - * publisher. + * publisher. * z_priority_t priority: The priority of messages issued by this publisher. - * bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. - * z_reliability_t reliability: (unstable) The reliability that should be used to transmit the data. + * bool is_express: If ``true``, Zenoh will not wait to batch this operation with others to reduce the bandwidth. + * z_reliability_t reliability: The reliability that should be used to transmit the data (unstable). */ typedef struct { z_moved_encoding_t *encoding; @@ -207,7 +207,7 @@ typedef struct { * z_congestion_control_t congestion_control: The congestion control to apply when routing this message. * z_priority_t priority: The priority of this message when routed. * z_timestamp_t *timestamp: The API level timestamp (e.g. of the data when it was created). - * bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. + * bool is_express: If ``true``, Zenoh will not wait to batch this operation with others to reduce the bandwidth. * z_moved_bytes_t* attachment: An optional attachment to the response. */ typedef struct { @@ -226,7 +226,7 @@ typedef struct { * z_congestion_control_t congestion_control: The congestion control to apply when routing this message. * z_priority_t priority: The priority of this message when routed. * z_timestamp_t *timestamp: The API level timestamp (e.g. of the data when it was created). - * bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. + * bool is_express: If ``true``, Zenoh will not wait to batch this operation with others to reduce the bandwidth. * z_moved_bytes_t* attachment: An optional attachment to the response. */ typedef struct { @@ -248,16 +248,16 @@ typedef struct { } z_query_reply_err_options_t; /** - * Represents the configuration used to configure a put operation sent via via :c:func:`z_put`. + * Represents the configuration used to configure a put operation sent via :c:func:`z_put`. * * Members: * z_moved_encoding_t* encoding: The encoding of the payload. * z_congestion_control_t congestion_control: The congestion control to apply when routing this message. * z_priority_t priority: The priority of this message when routed. * z_timestamp_t *timestamp: The API level timestamp (e.g. of the data when it was created). - * bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. + * bool is_express: If ``true``, Zenoh will not wait to batch this operation with others to reduce the bandwidth. * z_moved_bytes_t* attachment: An optional attachment to the publication. - * z_reliability_t reliability: (unstable) The reliability that should be used to transmit the data. + * z_reliability_t reliability: The reliability that should be used to transmit the data (unstable). */ typedef struct { z_moved_encoding_t *encoding; @@ -277,9 +277,9 @@ typedef struct { * Members: * z_congestion_control_t congestion_control: The congestion control to apply when routing this message. * z_priority_t priority: The priority of this message when router. - * bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. + * bool is_express: If ``true``, Zenoh will not wait to batch this operation with others to reduce the bandwidth. * z_timestamp_t *timestamp: The API level timestamp (e.g. of the data when it was created). - * z_reliability_t reliability: (unstable) The reliability that should be used to transmit the data. + * z_reliability_t reliability: The reliability that should be used to transmit the data (unstable). */ typedef struct { z_congestion_control_t congestion_control; @@ -326,7 +326,7 @@ typedef struct { * z_query_consolidation_t consolidation: The replies consolidation strategy to apply on replies. * z_congestion_control_t congestion_control: The congestion control to apply when routing the query. * z_priority_t priority: The priority of the query. - * bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. + * bool is_express: If ``true``, Zenoh will not wait to batch this operation with others to reduce the bandwidth. * z_query_target_t target: The queryables that should be targeted by this get. * z_moved_bytes_t* attachment: An optional attachment to the query. */