Docs comments celanup, fixes, etc. (#710)

* Docs comments celanup, fixes, etc. * Syntax and formatting fixes
eclipse-zenoh · Oct 7, 2024 · 61f7061 · 61f7061
1 parent 1a14906
commit 61f7061
Show file tree

Hide file tree

Showing 5 changed files with 244 additions and 292 deletions.
diff --git 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
@@ -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 <https://docs.python.org/3/library/pickle.html>`_.
  * 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 <https://github.com/OpenObservability/OpenMetrics>`_ data, commonly used by
+ * `Prometheus <https://prometheus.io/>`_.
  * Constant alias for string: `"application/openmetrics-text"`.
  */
 const z_loaned_encoding_t *z_encoding_application_openmetrics_text(void);