Fix doc warnings (#1197)

* Fix and Improve liveliness doc

* Fix doc warnings

* Add doc warnings check in CI

Author: OlivierHecart

.github/workflows/ci.yml

@@ -86,6 +86,11 @@ jobs:
       - name: Run doctests
         run: cargo test --doc
 
+      - name: Build doc
+        run: cargo doc --no-deps --features unstable
+        env:
+          RUSTDOCFLAGS: -Dwarnings
+
       - name: Check licenses
         run: cargo deny check licenses
 

commons/zenoh-keyexpr/src/key_expr/format/mod.rs

@@ -17,8 +17,8 @@
 //! The same issue arises naturally when designing a KE space, and [`KeFormat`] was designed to help you with this,
 //! both in constructing and in parsing KEs that fit the formats you've defined.
 //!
-//! [`kedefine`](https://docs.rs/zenoh/0.10.1-rc/zenoh/macro.kedefine.html) also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats,
-//! as the [`keformat`](https://docs.rs/zenoh/0.10.1-rc/zenoh/macro.keformat.html) and [`kewrite`](https://docs.rs/zenoh/0.10.1-rc/zenoh/macro.kewrite.html) macros will be able to tell you if you're attempting to set fields of the format that do not exist.
+//! [`kedefine`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.kedefine.html) also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats,
+//! as the [`keformat`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.keformat.htmll) and [`kewrite`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.kewrite.html) macros will be able to tell you if you're attempting to set fields of the format that do not exist.
 //!
 //! ## The format syntax
 //! KE formats are defined following a syntax that extends the [`keyexpr`] syntax. In addition to existing chunk types, KE formmats support "specification" chunks.
@@ -67,8 +67,8 @@ use support::{IterativeConstructor, Spec};
 /// The same issue arises naturally when designing a KE space, and [`KeFormat`] was designed to help you with this,
 /// both in constructing and in parsing KEs that fit the formats you've defined.
 ///
-/// [`zenoh::kedefine`](https://docs.rs/zenoh/0.10.1-rc/zenoh/macro.kedefine.html) also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats,
-/// as the [`zenoh::keformat`](https://docs.rs/zenoh/0.10.1-rc/zenoh/macro.keformat.html) and [`zenoh::kewrite`](https://docs.rs/zenoh/0.10.1-rc/zenoh/macro.kewrite.html) macros will be able to tell you if you're attempting to set fields of the format that do not exist.
+/// [`kedefine`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.kedefine.html) also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats,
+/// as the [`keformat`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.keformat.html) and [`kewrite`](https://docs.rs/zenoh/latest/zenoh/macro.kewrite.html) macros will be able to tell you if you're attempting to set fields of the format that do not exist.
 ///
 /// ## The format syntax
 /// KE formats are defined following a syntax that extends the [`keyexpr`] syntax. In addition to existing chunk types, KE formmats support "specification" chunks.
@@ -120,7 +120,7 @@ impl<'s> KeFormat<'s, Vec<Segment<'s>>> {
     ///
     /// `N` is simply the number of specifications in `value`. If this number of specs isn't known at compile-time, use [`KeFormat::new`] instead.
     ///
-    /// If you know `value` at compile time, using [`zenoh::kedefine`](https://docs.rs/zenoh/0.10.1-rc/zenoh/macro.kedefine.html) instead is advised,
+    /// If you know `value` at compile time, using [`kedefine`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.kedefine.html) instead is advised,
     /// as it will provide more features and construct higher performance formats than this constructor.
     pub fn noalloc_new<const N: usize>(value: &'s str) -> ZResult<KeFormat<'s, [Segment<'s>; N]>> {
         value.try_into()

commons/zenoh-keyexpr/src/keyexpr_tree/mod.rs

@@ -47,7 +47,7 @@
 //! # Iterators
 //! KeTrees provide iterators for the following operations:
 //! - Iterating on all nodes ([`IKeyExprTree::tree_iter`]/[`IKeyExprTreeMut::tree_iter_mut`])
-//! - Iterating on key-value pairs in the KeTree ([`IKeyExprTreeExt::key_value_pairs`])
+//! - Iterating on key-value pairs in the KeTree ([`IKeyExprTree::key_value_pairs`])
 //! - Iterating on nodes whose KE intersects with a queried KE ([`IKeyExprTree::intersecting_nodes`], [`IKeyExprTreeMut::intersecting_nodes_mut`])
 //! - Iterating on nodes whose KE are included by a queried KE ([`IKeyExprTree::included_nodes`], [`IKeyExprTreeMut::included_nodes_mut`])
 //! - Iterating on nodes whose KE includes a queried KE ([`IKeyExprTree::nodes_including`], [`IKeyExprTreeMut::nodes_including_mut`])

commons/zenoh-keyexpr/src/lib.rs

@@ -22,8 +22,8 @@
 //! # Storing Key Expressions
 //! This module provides 2 flavours to store strings that have been validated to respect the KE syntax, and a third is provided by [`zenoh`](https://docs.rs/zenoh):
 //! - [`keyexpr`] is the equivalent of a [`str`],
-//! - [`OwnedKeyExpr`] works like an [`Arc<str>`],
-//! - [`KeyExpr`](https://docs.rs/zenoh/latest/zenoh/key_expr/struct.KeyExpr.html) works like a [`Cow<str>`], but also stores some additional context internal to Zenoh to optimize
+//! - [`OwnedKeyExpr`] works like an [`Arc<str>`](std::sync::Arc),
+//! - [`KeyExpr`](https://docs.rs/zenoh/latest/zenoh/key_expr/struct.KeyExpr.html) works like a [`Cow<str>`](std::borrow::Cow), but also stores some additional context internal to Zenoh to optimize
 //! routing and network usage.
 //!
 //! All of these types [`Deref`](core::ops::Deref) to [`keyexpr`], which notably has methods to check whether a given [`keyexpr::intersects`] with another,
@@ -40,8 +40,8 @@
 //! The same issue arises naturally when designing a KE space, and [`KeFormat`](format::KeFormat) was designed to help you with this,
 //! both in constructing and in parsing KEs that fit the formats you've defined.
 //!
-//! [`kedefine`] also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats,
-//! as the [`keformat`] and [`kewrite`] macros will be able to tell you if you're attempting to set fields of the format that do not exist.
+//! [`kedefine`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.kedefine.html) also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats,
+//! as the [`keformat`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.keformat.html) and [`kewrite`](https://docs.rs/zenoh/latest/zenoh/key_expr/format/macro.kewrite.html) macros will be able to tell you if you're attempting to set fields of the format that do not exist.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 extern crate alloc;

commons/zenoh-protocol/src/core/mod.rs

@@ -273,7 +273,7 @@ impl<'de> serde::Deserialize<'de> for ZenohIdProto {
     }
 }
 
-/// The unique id of a zenoh entity inside it's parent [`Session`].
+/// The unique id of a zenoh entity inside it's parent `Session`.
 pub type EntityId = u32;
 
 /// The global unique id of a zenoh entity.

commons/zenoh-protocol/src/core/parameters.rs

@@ -50,7 +50,7 @@ pub fn iter(s: &str) -> impl DoubleEndedIterator<Item = (&str, &str)> + Clone {
         .map(|p| split_once(p, FIELD_SEPARATOR))
 }
 
-/// Same as [`Self::from_iter_into`] but keys are sorted in alphabetical order.
+/// Same as [`from_iter_into`] but keys are sorted in alphabetical order.
 pub fn sort<'s, I>(iter: I) -> impl Iterator<Item = (&'s str, &'s str)>
 where
     I: Iterator<Item = (&'s str, &'s str)>,
@@ -84,7 +84,7 @@ where
     into
 }
 
-/// Same as [`Self::from_iter`] but it writes into a user-provided string instead of allocating a new one.
+/// Same as [`from_iter`] but it writes into a user-provided string instead of allocating a new one.
 pub fn from_iter_into<'s, I>(iter: I, into: &mut String)
 where
     I: Iterator<Item = (&'s str, &'s str)>,
@@ -131,7 +131,7 @@ pub fn insert<'s>(s: &'s str, k: &'s str, v: &'s str) -> (String, Option<&'s str
     (from_iter(iter), item)
 }
 
-/// Same as [`Self::insert`] but keys are sorted in alphabetical order.
+/// Same as [`insert`] but keys are sorted in alphabetical order.
 pub fn insert_sort<'s>(s: &'s str, k: &'s str, v: &'s str) -> (String, Option<&'s str>) {
     let (iter, item) = _insert(iter(s), k, v);
     (from_iter(sort(iter)), item)

commons/zenoh-protocol/src/network/declare.rs

@@ -32,6 +32,7 @@ pub mod flag {
     pub const Z: u8 = 1 << 7; // 0x80 Extensions    if Z==1 then an extension will follow
 }
 
+/// ```text
 /// Flags:
 /// - I: Interest       If I==1 then interest_id is present
 /// - X: Reserved
@@ -47,7 +48,7 @@ pub mod flag {
 /// +---------------+
 /// ~  declaration  ~
 /// +---------------+
-///
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Declare {
     pub interest_id: Option<super::interest::InterestId>,
@@ -178,6 +179,7 @@ pub mod common {
     pub mod ext {
         use super::*;
 
+        /// ```text
         /// Flags:
         /// - N: Named          If N==1 then the key expr has name/suffix
         /// - M: Mapping        if M==1 then key expr mapping is the one declared by the sender, else it is the one declared by the receiver
@@ -190,7 +192,7 @@ pub mod common {
         /// +---------------+
         /// ~  key_suffix   ~  if N==1 -- <u8;z16>
         /// +---------------+
-        ///
+        /// ```
         pub type WireExprExt = zextzbuf!(0x0f, true);
         #[derive(Debug, Clone, PartialEq, Eq)]
         pub struct WireExprType {
@@ -513,6 +515,7 @@ pub mod queryable {
             pub const C: u8 = 1; // 0x01 Complete      if C==1 then the queryable is complete
         }
         ///
+        /// ```text
         ///  7 6 5 4 3 2 1 0
         /// +-+-+-+-+-+-+-+-+
         /// |Z|0_1|    ID   |
@@ -521,6 +524,7 @@ pub mod queryable {
         /// +---------------+
         /// ~ distance <z16>~
         /// +---------------+
+        /// ```
         #[derive(Debug, Clone, Copy, PartialEq, Eq)]
         pub struct QueryableInfoType {
             pub complete: bool, // Default false: incomplete

commons/zenoh-protocol/src/network/mod.rs

@@ -418,6 +418,7 @@ pub mod ext {
         }
     }
 
+    /// ```text
     ///  7 6 5 4 3 2 1 0
     /// +-+-+-+-+-+-+-+-+
     /// |zid_len|X|X|X|X|
@@ -426,6 +427,7 @@ pub mod ext {
     /// +---------------+
     /// %      eid      %
     /// +---------------+
+    /// ```
     #[derive(Debug, Clone, PartialEq, Eq)]
     pub struct EntityGlobalIdType<const ID: u8> {
         pub zid: ZenohIdProto,

commons/zenoh-protocol/src/network/request.rs

@@ -82,12 +82,13 @@ pub mod ext {
     pub type NodeIdType = crate::network::ext::NodeIdType<{ NodeId::ID }>;
 
     pub type Target = zextz64!(0x4, true);
+    /// ```text
     /// - Target (0x03)
     ///  7 6 5 4 3 2 1 0
     /// +-+-+-+-+-+-+-+-+
     /// %     target    %
     /// +---------------+
-    ///
+    /// ```
     /// The `zenoh::queryable::Queryable`s that should be target of a `zenoh::Session::get()`.
     #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
     pub enum TargetType {

commons/zenoh-protocol/src/scouting/hello.rs

@@ -17,8 +17,8 @@ use crate::core::{Locator, WhatAmI, ZenohIdProto};
 
 /// # Hello message
 ///
-/// The [`Hello`] message is used to advertise the locators a zenoh node is reachable at.
-/// The [`Hello`] message SHOULD be sent in a unicast fashion in response to a [`super::Scout`]
+/// The `Hello` message is used to advertise the locators a zenoh node is reachable at.
+/// The `Hello` message SHOULD be sent in a unicast fashion in response to a [`super::Scout`]
 /// message as shown below:
 ///
 /// ```text
@@ -34,7 +34,7 @@ use crate::core::{Locator, WhatAmI, ZenohIdProto};
 /// |                   |                   |
 /// ```
 ///
-/// Moreover, a [`Hello`] message MAY be sent in the network in a multicast
+/// Moreover, a `Hello` message MAY be sent in the network in a multicast
 /// fashion to advertise the presence of zenoh node. The advertisement operation MAY be performed
 /// periodically as shown below:
 ///
@@ -54,7 +54,7 @@ use crate::core::{Locator, WhatAmI, ZenohIdProto};
 /// |                   |                   |
 /// ```
 ///
-/// Examples of locators included in the [`Hello`] message are:
+/// Examples of locators included in the `Hello` message are:
 ///
 /// ```text
 ///  udp/192.168.1.1:7447
@@ -63,7 +63,7 @@ use crate::core::{Locator, WhatAmI, ZenohIdProto};
 ///  tcp/localhost:7447
 /// ```
 ///
-/// The [`Hello`] message structure is defined as follows:
+/// The `Hello` message structure is defined as follows:
 ///
 /// ```text
 /// Header flags:

commons/zenoh-protocol/src/scouting/scout.rs

@@ -18,7 +18,7 @@ use crate::core::{whatami::WhatAmIMatcher, ZenohIdProto};
 /// The [`Scout`] message MAY be sent at any point in time to discover the available zenoh nodes in the
 /// network. The [`Scout`] message SHOULD be sent in a multicast or broadcast fashion. Upon receiving a
 /// [`Scout`] message, a zenoh node MUST first verify whether the matching criteria are satisfied, then
-/// it SHOULD reply with a [`super::Hello`] message in a unicast fashion including all the requested
+/// it SHOULD reply with a [`super::HelloProto`] message in a unicast fashion including all the requested
 /// information.
 ///
 /// The scouting message flow is the following:

commons/zenoh-protocol/src/transport/fragment.rs

@@ -18,7 +18,7 @@ pub use crate::transport::TransportSn;
 
 /// # Fragment message
 ///
-/// The [`Fragment`] message is used to transmit on the wire large [`crate::zenoh::ZenohMessage`]
+/// The [`Fragment`] message is used to transmit on the wire large [`crate::network::NetworkMessage`]
 /// that require fragmentation because they are larger than the maximum batch size
 /// (i.e. 2^16-1) and/or the link MTU.
 ///

commons/zenoh-protocol/src/transport/frame.rs

@@ -18,11 +18,11 @@ use crate::{core::Reliability, network::NetworkMessage, transport::TransportSn};
 /// # Frame message
 ///
 /// The [`Frame`] message is used to transmit one ore more complete serialized
-/// [`crate::net::protocol::message::ZenohMessage`]. I.e., the total length of the
-/// serialized [`crate::net::protocol::message::ZenohMessage`] (s) MUST be smaller
+/// [`crate::network::NetworkMessage`]. I.e., the total length of the
+/// serialized [`crate::network::NetworkMessage`] (s) MUST be smaller
 /// than the maximum batch size (i.e. 2^16-1) and the link MTU.
 /// The [`Frame`] message is used as means to aggregate multiple
-/// [`crate::net::protocol::message::ZenohMessage`] in a single atomic message that
+/// [`crate::network::NetworkMessage`] in a single atomic message that
 /// goes on the wire. By doing so, many small messages can be batched together and
 /// share common information like the sequence number.
 ///

commons/zenoh-protocol/src/transport/mod.rs

@@ -255,11 +255,13 @@ impl fmt::Display for TransportMessage {
 pub mod ext {
     use crate::{common::ZExtZ64, core::Priority};
 
+    /// ```text
     ///  7 6 5 4 3 2 1 0
     /// +-+-+-+-+-+-+-+-+
     /// %0|  rsv  |prio %
     /// +---------------+
     /// - prio: Priority class
+    /// ```
     #[repr(transparent)]
     #[derive(Debug, Clone, Copy, PartialEq, Eq)]
     pub struct QoSType<const ID: u8> {

commons/zenoh-protocol/src/zenoh/mod.rs

@@ -138,6 +138,7 @@ pub mod ext {
 
     use crate::core::{Encoding, EntityGlobalIdProto};
 
+    /// ```text
     ///  7 6 5 4 3 2 1 0
     /// +-+-+-+-+-+-+-+-+
     /// |zid_len|X|X|X|X|
@@ -148,6 +149,7 @@ pub mod ext {
     /// +---------------+
     /// %      sn       %
     /// +---------------+
+    /// ```
     #[derive(Debug, Clone, PartialEq, Eq)]
     pub struct SourceInfoType<const ID: u8> {
         pub id: EntityGlobalIdProto,

commons/zenoh-util/src/log.rs

@@ -27,7 +27,7 @@ use tracing_subscriber::{
 /// Calling this function initializes a `lazy_static` in the `tracing` crate
 /// such static is not deallocated prior to process existing, thus tools such as `valgrind`
 /// will report a memory leak.
-/// Refer to this issue: https://github.com/tokio-rs/tracing/issues/2069
+/// Refer to this issue: <https://github.com/tokio-rs/tracing/issues/2069>
 pub fn try_init_log_from_env() {
     if let Ok(env_filter) = EnvFilter::try_from_default_env() {
         init_env_filter(env_filter);
@@ -41,7 +41,7 @@ pub fn try_init_log_from_env() {
 /// Calling this function initializes a `lazy_static` in the `tracing` crate
 /// such static is not deallocated prior to process existing, thus tools such as `valgrind`
 /// will report a memory leak.
-/// Refer to this issue: https://github.com/tokio-rs/tracing/issues/2069
+/// Refer to this issue: <https://github.com/tokio-rs/tracing/issues/2069>
 pub fn init_log_from_env_or<S>(fallback: S)
 where
     S: AsRef<str>,

io/zenoh-transport/src/common/batch.rs

@@ -149,7 +149,7 @@ impl BatchHeader {
         self.0
     }
 
-    /// Verify that the [`WBatch`][WBatch] is for a stream-based protocol, i.e., the first
+    /// Verify that the [`WBatch`] is for a stream-based protocol, i.e., the first
     /// 2 bytes are reserved to encode the total amount of serialized bytes as 16-bits little endian.
     #[cfg(feature = "transport_compression")]
     #[inline(always)]
@@ -181,22 +181,22 @@ pub enum Finalize {
 
 /// Write Batch
 ///
-/// A [`WBatch`][WBatch] is a non-expandable and contiguous region of memory
-/// that is used to serialize [`TransportMessage`][TransportMessage] and [`ZenohMessage`][ZenohMessage].
+/// A [`WBatch`] is a non-expandable and contiguous region of memory
+/// that is used to serialize [`TransportMessage`] and [`NetworkMessage`].
 ///
-/// [`TransportMessage`][TransportMessage] are always serialized on the batch as they are, while
-/// [`ZenohMessage`][ZenohMessage] are always serializaed on the batch as part of a [`TransportMessage`]
+/// [`TransportMessage`] are always serialized on the batch as they are, while
+/// [`NetworkMessage`] are always serializaed on the batch as part of a [`TransportMessage`]
 /// [TransportMessage] Frame. Reliable and Best Effort Frames can be interleaved on the same
-/// [`WBatch`][WBatch] as long as they fit in the remaining buffer capacity.
+/// [`WBatch`] as long as they fit in the remaining buffer capacity.
 ///
-/// In the serialized form, the [`WBatch`][WBatch] always contains one or more
-/// [`TransportMessage`][TransportMessage]. In the particular case of [`TransportMessage`][TransportMessage] Frame,
-/// its payload is either (i) one or more complete [`ZenohMessage`][ZenohMessage] or (ii) a fragment of a
-/// a [`ZenohMessage`][ZenohMessage].
+/// In the serialized form, the [`WBatch`] always contains one or more
+/// [`TransportMessage`]. In the particular case of [`TransportMessage`] Frame,
+/// its payload is either (i) one or more complete [`NetworkMessage`] or (ii) a fragment of a
+/// a [`NetworkMessage`].
 ///
-/// As an example, the content of the [`WBatch`][WBatch] in memory could be:
+/// As an example, the content of the [`WBatch`] in memory could be:
 ///
-/// | Keep Alive | Frame Reliable<Zenoh Message, Zenoh Message> | Frame Best Effort<Zenoh Message Fragment> |
+/// | Keep Alive | Frame Reliable\<Zenoh Message, Zenoh Message\> | Frame Best Effort\<Zenoh Message Fragment\> |
 ///
 #[derive(Clone, Debug)]
 pub struct WBatch {
@@ -227,20 +227,20 @@ impl WBatch {
         batch
     }
 
-    /// Verify that the [`WBatch`][WBatch] has no serialized bytes.
+    /// Verify that the [`WBatch`] has no serialized bytes.
     #[inline(always)]
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
 
-    /// Get the total number of bytes that have been serialized on the [`WBatch`][WBatch].
+    /// Get the total number of bytes that have been serialized on the [`WBatch`].
     #[inline(always)]
     pub fn len(&self) -> BatchSize {
         let (_l, _h, p) = Self::split(self.buffer.as_slice(), &self.config);
         p.len() as BatchSize
     }
 
-    /// Clear the [`WBatch`][WBatch] memory buffer and related internal state.
+    /// Clear the [`WBatch`] memory buffer and related internal state.
     #[inline(always)]
     pub fn clear(&mut self) {
         self.buffer.clear();