Add liveliness documentation

docs/api.rst

@@ -262,6 +262,28 @@ Functions
 .. autocfunction:: zenoh_commons.h::z_closure_query_call
 .. autocfunction:: zenoh_commons.h::z_closure_query_drop
 
+Liveliness
+==========
+
+Types
+-----
+
+.. autocstruct:: zenoh_commons.h::zc_owned_liveliness_token_t
+.. autocstruct:: zenoh_commons.h::zc_owned_liveliness_declaration_options_t
+.. autocstruct:: zenoh_commons.h::zc_owned_liveliness_get_options_t
+.. autocstruct:: zenoh_commons.h::zc_owned_liveliness_declare_subscriber_options_t
+
+Functions
+---------
+
+.. autocfunction:: zenoh_commons.h::zc_liveliness_declare_token
+.. autocfunction:: zenoh_commons.h::zc_liveliness_undeclare_token
+.. autocfunction:: zenoh_commons.h::zc_liveliness_token_null
+.. autocfunction:: zenoh_commons.h::zc_liveliness_token_check
+.. autocfunction:: zenoh_commons.h::zc_liveliness_declare_subscriber
+.. autocfunction:: zenoh_commons.h::zc_liveliness_get
+.. autocfunction:: zenoh_commons.h::zc_liveliness_get_options_default
+
 Publication Cache
 =================
 
@@ -275,7 +297,7 @@ Functions
 ---------
 
 .. autocfunction:: zenoh_commons.h::ze_declare_publication_cache
-.. autocfunction:: zenoh_commons.h::ze_close_publication_cache
+.. autocfunction:: zenoh_commons.h::ze_undeclare_publication_cache
 .. autocfunction:: zenoh_commons.h::ze_publication_cache_check
 .. autocfunction:: zenoh_commons.h::ze_publication_cache_null
 .. autocfunction:: zenoh_commons.h::ze_publication_cache_options_default

include/zenoh_commons.h

@@ -683,7 +683,7 @@ typedef struct zc_owned_liveliness_declaration_options_t {
   uint8_t _inner;
 } zc_owned_liveliness_declaration_options_t;
 /**
- * The options for `zc_liveliness_declare_subscriber`
+ * The options for :c:func:`zc_liveliness_declare_subscriber`
  */
 typedef struct zc_owned_liveliness_declare_subscriber_options_t {
   uint8_t _inner;
@@ -699,7 +699,7 @@ typedef struct zc_owned_liveliness_token_t {
   uintptr_t _inner[4];
 } zc_owned_liveliness_token_t;
 /**
- * The options for `zc_liveliness_declare_subscriber`
+ * The options for :c:func:`zc_liveliness_declare_subscriber`
  */
 typedef struct zc_owned_liveliness_get_options_t {
   uint32_t timeout_ms;
@@ -1753,7 +1753,18 @@ struct zc_owned_liveliness_declaration_options_t zc_liveliness_declaration_optio
 /**
  * Declares a subscriber on liveliness tokens that intersect `key`.
  *
- * Passing `NULL` as options is valid and equivalent to passing a pointer to the default options.
+ * Parameters:
+ *     z_session_t session: The zenoh session.
+ *     z_keyexpr_t keyexpr: The key expression to subscribe.
+ *     z_owned_closure_sample_t callback: The callback function that will be called each time a
+ *                                        liveliness token status changed.
+ *     zc_owned_liveliness_declare_subscriber_options_t _options: The options to be passed to describe the options to be passed to the liveliness subscriber declaration.
+ *
+ * Returns:
+ *    A :c:type:`z_owned_subscriber_t`.
+ *
+ *    To check if the subscription succeeded and if the subscriber is still valid,
+ *    you may use `z_subscriber_check(&val)` or `z_check(val)` if your compiler supports `_Generic`, which will return `true` if `val` is valid.
  */
 ZENOHC_API
 struct z_owned_subscriber_t zc_liveliness_declare_subscriber(struct z_session_t session,
@@ -1775,7 +1786,7 @@ struct zc_owned_liveliness_token_t zc_liveliness_declare_token(struct z_session_
 /**
  * Queries liveliness tokens currently on the network with a key expression intersecting with `key`.
  *
- * Note that the same "value stealing" tricks apply as with a normal `z_get`
+ * Note that the same "value stealing" tricks apply as with a normal :c:func:`z_get`
  *
  * Passing `NULL` as options is valid and equivalent to passing a pointer to the default options.
  */

src/liveliness.rs

@@ -121,7 +121,7 @@ pub extern "C" fn zc_liveliness_undeclare_token(token: &mut zc_owned_liveliness_
     }
 }
 
-/// The options for `zc_liveliness_declare_subscriber`
+/// The options for :c:func:`zc_liveliness_declare_subscriber`
 #[repr(C)]
 pub struct zc_owned_liveliness_declare_subscriber_options_t {
     _inner: u8,
@@ -149,7 +149,18 @@ pub extern "C" fn zc_liveliness_subscriber_options_drop(
 
 /// Declares a subscriber on liveliness tokens that intersect `key`.
 ///
-/// Passing `NULL` as options is valid and equivalent to passing a pointer to the default options.
+/// Parameters:
+///     z_session_t session: The zenoh session.
+///     z_keyexpr_t keyexpr: The key expression to subscribe.
+///     z_owned_closure_sample_t callback: The callback function that will be called each time a
+///                                        liveliness token status changed.
+///     zc_owned_liveliness_declare_subscriber_options_t _options: The options to be passed to describe the options to be passed to the liveliness subscriber declaration.
+///
+/// Returns:
+///    A :c:type:`z_owned_subscriber_t`.
+///
+///    To check if the subscription succeeded and if the subscriber is still valid,
+///    you may use `z_subscriber_check(&val)` or `z_check(val)` if your compiler supports `_Generic`, which will return `true` if `val` is valid.
 #[no_mangle]
 pub extern "C" fn zc_liveliness_declare_subscriber(
     session: z_session_t,
@@ -184,7 +195,7 @@ pub extern "C" fn zc_liveliness_declare_subscriber(
     }
 }
 
-/// The options for `zc_liveliness_declare_subscriber`
+/// The options for :c:func:`zc_liveliness_declare_subscriber`
 #[repr(C)]
 pub struct zc_owned_liveliness_get_options_t {
     timeout_ms: u32,
@@ -214,7 +225,7 @@ pub extern "C" fn zc_liveliness_get_options_drop(opts: &mut zc_owned_liveliness_
 
 /// Queries liveliness tokens currently on the network with a key expression intersecting with `key`.
 ///
-/// Note that the same "value stealing" tricks apply as with a normal `z_get`
+/// Note that the same "value stealing" tricks apply as with a normal :c:func:`z_get`
 ///
 /// Passing `NULL` as options is valid and equivalent to passing a pointer to the default options.
 #[no_mangle]