'history' and 'timeout_ms' options are documented (eclipse-zenoh#824)

* members added to doc * doc comment added * doc corrected, warning on build doc fixed * macro header update * doc updated * doc updated
DenisBiryukov91 · Dec 3, 2024 · 752d7b5 · 752d7b5
1 parent 612f534
commit 752d7b5
Show file tree

Hide file tree

Showing 6 changed files with 28 additions and 16 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -6,6 +6,7 @@ zenoh-c API documentation is available on [Read the Docs](https://zenoh-c.readth
 ## How to build it
 
 ```bash
+cargo check --all-features
 cd docs
 doxygen
 sphinx-build -b html . _build/html

diff --git a/docs/api.rst b/docs/api.rst
@@ -855,8 +855,11 @@ Types
 
 .. doxygenstruct:: z_owned_liveliness_token_t
 .. doxygenstruct:: z_liveliness_token_options_t
+    :members:
 .. doxygenstruct:: z_liveliness_get_options_t
+    :members:
 .. doxygenstruct:: z_liveliness_subscriber_options_t
+    :members:
 
 Functions
 ---------

diff --git a/include/zenoh_commons.h b/include/zenoh_commons.h
@@ -763,6 +763,9 @@ typedef struct z_moved_keyexpr_t {
  */
 #if defined(Z_FEATURE_UNSTABLE_API)
 typedef struct z_liveliness_subscriber_options_t {
+  /**
+   * If true, subscriber will receive the state change notifications for liveliness tokens that were declared before its declaration.
+   */
   bool history;
 } z_liveliness_subscriber_options_t;
 #endif
@@ -781,6 +784,9 @@ typedef struct z_liveliness_token_options_t {
  */
 #if defined(Z_FEATURE_UNSTABLE_API)
 typedef struct z_liveliness_get_options_t {
+  /**
+   * The timeout for the liveliness query in milliseconds. 0 means default query timeout from zenoh configuration.
+   */
   uint32_t timeout_ms;
 } z_liveliness_get_options_t;
 #endif
@@ -1314,7 +1320,7 @@ void z_alloc_layout_alloc_gc(struct z_buf_alloc_result_t *out_result,
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation if needed.
+ * @brief Make allocation performing garbage collection and/or defragmentation if needed.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
 ZENOHC_API
@@ -1323,7 +1329,7 @@ void z_alloc_layout_alloc_gc_defrag(struct z_buf_alloc_result_t *out_result,
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation and\or blocking if needed.
+ * @brief Make allocation performing garbage collection and/or defragmentation and/or blocking if needed.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
 ZENOHC_API
@@ -1332,7 +1338,7 @@ void z_alloc_layout_alloc_gc_defrag_blocking(struct z_buf_alloc_result_t *out_re
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation and\or forced deallocation if needed.
+ * @brief Make allocation performing garbage collection and/or defragmentation and/or forced deallocation if needed.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
 ZENOHC_API
@@ -1368,7 +1374,7 @@ z_result_t z_alloc_layout_new(z_owned_alloc_layout_t *this_,
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation in async manner. Will return Z_EINVAL
+ * @brief Make allocation performing garbage collection and/or defragmentation in async manner. Will return Z_EINVAL
  * if used with non-threadsafe SHM Provider.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
@@ -4321,7 +4327,7 @@ void z_shm_provider_alloc_gc(struct z_buf_layout_alloc_result_t *out_result,
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation if needed.
+ * @brief Make allocation performing garbage collection and/or defragmentation if needed.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
 ZENOHC_API
@@ -4332,7 +4338,7 @@ void z_shm_provider_alloc_gc_defrag(struct z_buf_layout_alloc_result_t *out_resu
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation in async manner. Will return Z_EINVAL
+ * @brief Make allocation performing garbage collection and/or defragmentation in async manner. Will return Z_EINVAL
  * if used with non-threadsafe SHM Provider.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
@@ -4347,7 +4353,7 @@ z_result_t z_shm_provider_alloc_gc_defrag_async(struct z_buf_layout_alloc_result
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation and\or blocking if needed.
+ * @brief Make allocation performing garbage collection and/or defragmentation and/or blocking if needed.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
 ZENOHC_API
@@ -4358,7 +4364,7 @@ void z_shm_provider_alloc_gc_defrag_blocking(struct z_buf_layout_alloc_result_t
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Make allocation performing garbage collection and\or defragmentation and\or forced deallocation if needed.
+ * @brief Make allocation performing garbage collection and/or defragmentation and/or forced deallocation if needed.
  */
 #if (defined(Z_FEATURE_SHARED_MEMORY) && defined(Z_FEATURE_UNSTABLE_API))
 ZENOHC_API

diff --git a/src/liveliness.rs b/src/liveliness.rs
@@ -138,6 +138,7 @@ pub extern "C" fn z_liveliness_undeclare_token(
 /// @brief The options for `z_liveliness_declare_subscriber()`
 #[repr(C)]
 pub struct z_liveliness_subscriber_options_t {
+    /// If true, subscriber will receive the state change notifications for liveliness tokens that were declared before its declaration.
     history: bool,
 }
 
@@ -237,6 +238,7 @@ pub extern "C" fn zc_liveliness_declare_background_subscriber(
 /// @brief The options for `z_liveliness_get()`
 #[repr(C)]
 pub struct z_liveliness_get_options_t {
+    /// The timeout for the liveliness query in milliseconds. 0 means default query timeout from zenoh configuration.
     timeout_ms: u32,
 }
 

diff --git a/src/shm/provider/alloc_layout.rs b/src/shm/provider/alloc_layout.rs
@@ -117,7 +117,7 @@ pub extern "C" fn z_alloc_layout_alloc_gc(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation if needed.
+/// @brief Make allocation performing garbage collection and/or defragmentation if needed.
 #[no_mangle]
 pub extern "C" fn z_alloc_layout_alloc_gc_defrag(
     out_result: &mut MaybeUninit<z_buf_alloc_result_t>,
@@ -127,7 +127,7 @@ pub extern "C" fn z_alloc_layout_alloc_gc_defrag(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation and\or forced deallocation if needed.
+/// @brief Make allocation performing garbage collection and/or defragmentation and/or forced deallocation if needed.
 #[no_mangle]
 pub extern "C" fn z_alloc_layout_alloc_gc_defrag_dealloc(
     out_result: &mut MaybeUninit<z_buf_alloc_result_t>,
@@ -137,7 +137,7 @@ pub extern "C" fn z_alloc_layout_alloc_gc_defrag_dealloc(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation and\or blocking if needed.
+/// @brief Make allocation performing garbage collection and/or defragmentation and/or blocking if needed.
 #[no_mangle]
 pub extern "C" fn z_alloc_layout_alloc_gc_defrag_blocking(
     out_result: &mut MaybeUninit<z_buf_alloc_result_t>,
@@ -147,7 +147,7 @@ pub extern "C" fn z_alloc_layout_alloc_gc_defrag_blocking(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation in async manner. Will return Z_EINVAL
+/// @brief Make allocation performing garbage collection and/or defragmentation in async manner. Will return Z_EINVAL
 /// if used with non-threadsafe SHM Provider.
 #[no_mangle]
 pub extern "C" fn z_alloc_layout_threadsafe_alloc_gc_defrag_async(

diff --git a/src/shm/provider/shm_provider.rs b/src/shm/provider/shm_provider.rs
@@ -154,7 +154,7 @@ pub extern "C" fn z_shm_provider_alloc_gc(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation if needed.
+/// @brief Make allocation performing garbage collection and/or defragmentation if needed.
 #[no_mangle]
 pub extern "C" fn z_shm_provider_alloc_gc_defrag(
     out_result: &mut MaybeUninit<z_buf_layout_alloc_result_t>,
@@ -166,7 +166,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation and\or forced deallocation if needed.
+/// @brief Make allocation performing garbage collection and/or defragmentation and/or forced deallocation if needed.
 #[no_mangle]
 pub extern "C" fn z_shm_provider_alloc_gc_defrag_dealloc(
     out_result: &mut MaybeUninit<z_buf_layout_alloc_result_t>,
@@ -178,7 +178,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_dealloc(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation and\or blocking if needed.
+/// @brief Make allocation performing garbage collection and/or defragmentation and/or blocking if needed.
 #[no_mangle]
 pub extern "C" fn z_shm_provider_alloc_gc_defrag_blocking(
     out_result: &mut MaybeUninit<z_buf_layout_alloc_result_t>,
@@ -190,7 +190,7 @@ pub extern "C" fn z_shm_provider_alloc_gc_defrag_blocking(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Make allocation performing garbage collection and\or defragmentation in async manner. Will return Z_EINVAL
+/// @brief Make allocation performing garbage collection and/or defragmentation in async manner. Will return Z_EINVAL
 /// if used with non-threadsafe SHM Provider.
 #[no_mangle]
 pub extern "C" fn z_shm_provider_alloc_gc_defrag_async(
-Original file line number
+Diff line change
@@ Expand Up @@
     ## How to build it
     ```bash
+    cargo check --all-features
     cd docs
     doxygen
     sphinx-build -b html . _build/html
@@ Expand Down @@