diff --git a/commons/zenoh-util/src/log.rs b/commons/zenoh-util/src/log.rs index a2e4a32e71..77d780ae90 100644 --- a/commons/zenoh-util/src/log.rs +++ b/commons/zenoh-util/src/log.rs @@ -22,13 +22,13 @@ use tracing_subscriber::{ /// A utility function to enable the tracing formatting subscriber. /// -/// The tracing formatting subscriber is initialized from the `RUST_LOG` environment variable. +/// The [`tracing_subscriber`]` is initialized from the `RUST_LOG` environment variable. /// If `RUST_LOG` is not set, then logging is not enabled. /// /// # Safety /// -/// 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` +/// Calling this function initializes a `lazy_static` in the [`tracing`] crate. +/// Such static is not deallocated prior to process exiting, thus tools such as `valgrind` /// will report a memory leak. /// Refer to this issue: pub fn try_init_log_from_env() { @@ -39,12 +39,12 @@ pub fn try_init_log_from_env() { /// A utility function to enable the tracing formatting subscriber. /// -/// The tracing formatting subscriber is initialized from the `RUST_LOG` environment variable. +/// The [`tracing_subscriber`] is initialized from the `RUST_LOG` environment variable. /// If `RUST_LOG` is not set, then fallback directives are used. /// /// # Safety -/// 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` +/// 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: pub fn init_log_from_env_or(fallback: S) diff --git a/zenoh/src/lib.rs b/zenoh/src/lib.rs index 0443560661..701e13fc94 100644 --- a/zenoh/src/lib.rs +++ b/zenoh/src/lib.rs @@ -180,6 +180,8 @@ pub mod key_expr { } /// Zenoh [`Session`] and associated types +/// +/// The [`Session`] is the main component of the Zenoh. pub mod session { #[zenoh_macros::unstable] pub use zenoh_config::wrappers::EntityGlobalId; @@ -202,6 +204,9 @@ pub mod session { } /// Sample primitives +/// +/// The [`Sample`](crate::sample::Sample) structure is the data unit received from [`Subscriber`](crate::pubsub::Subscriber) +/// or [`Queryable`](crate::query::Queryable) instances. It contains the payload and all the metadata associated with the data. pub mod sample { #[zenoh_macros::unstable] pub use crate::api::sample::Locality; @@ -216,6 +221,16 @@ pub mod sample { } /// Payload primitives +/// +/// The [`ZBytes`](crate::bytes::ZBytes) type is Zenoh's representation of raw byte data. +/// It provides mechanisms for zero-copy creation and access (`From>` and +/// [`ZBytes::slices`](crate::bytes::ZBytes::slices)), as well as methods for sequential +/// reading/writing ([`ZBytes::reader`](crate::bytes::ZBytes::reader), [`ZBytes::writer`](crate::bytes::ZBytes::writer)). +/// +/// The`zenoh_ext` crate provides serialization and deserialization of basic types and structures for `ZBytes` +/// [`z_serialize`](../../zenoh_ext/fn.z_serialize.html) / +/// [`z_deserialize`](../../zenoh_ext/fn.z_deserialize.html). + pub mod bytes { pub use crate::api::{ bytes::{OptionZBytes, ZBytes, ZBytesReader, ZBytesSliceIterator, ZBytesWriter}, @@ -224,6 +239,14 @@ pub mod bytes { } /// Pub/sub primitives +/// +/// The [`Publisher`](crate::pubsub::Publisher) instance is declared by a +/// [`Session::declare_publisher`](crate::Session::declare_publisher) method. +/// +/// The data [`Sample`](crate::sample::Sample)s +/// are received by [`Subscriber`](crate::pubsub::Subscriber)s +/// declared by a [`Session::declare_subscriber`](crate::Session::declare_subscriber) +/// pub mod pubsub { #[zenoh_macros::unstable] pub use crate::api::{ @@ -244,6 +267,12 @@ pub mod pubsub { } /// Query/reply primitives +/// +/// The [`Queryable`](crate::query::Queryable) instance is declared by a +/// [`Session::declare_queryable`](crate::Session::declare_queryable) method. +/// It is requested by a [`Session::get`](crate::Session::get) operation which +/// receives data in [`Reply`](crate::query::Reply) structures. +/// pub mod query { pub use zenoh_protocol::core::Parameters; #[zenoh_macros::unstable] @@ -264,7 +293,35 @@ pub mod query { pub use crate::api::{query::ReplyKeyExpr, selector::ZenohParameters}; } -/// Callback handler trait +/// Callback handler trait. +/// +/// Zenoh primitives that receive data (e.g., [`Subscriber`](crate::pubsub::Subscriber), +/// [`Query`](crate::query::Query), etc.) have a +/// [`with`](crate::pubsub::SubscriberBuilder::with) method which accepts a handler for the data. +/// +/// The handler is a pair of a [`Callback`](crate::handlers::Callback) and an arbitrary `Handler` +/// object used to access data received by the callback. When the data is processed by the callback itself +/// the handler type can be `()`. For convenience, the +/// [`callback`](crate::pubsub::SubscriberBuilder::callback) method, which accepts +/// a `Fn(T)` only can be used in this case. +/// +/// The [`with`](crate::pubsub::SubscriberBuilder::with) method accepts any type that +/// implements the [`IntoHandler`](crate::handlers::IntoHandler) trait, which provides a +/// conversion to a pair of [`Callback`](crate::handlers::Callback) and handler. +/// +/// The `IntoHandler` for channels [`FifoChannel`](crate::handlers::FifoChannel) and +/// [`RingChannel`](crate::handlers::RingChannel) +/// return a pair of ([`Callback`](crate::handlers::Callback), channel_handler). +/// +/// The callback pushes data to the channel, the +/// channel handler [`FifoChannelHandler`](crate::handlers::FifoChannelHandler) or +/// [`RingChannelHandler`](crate::handlers::RingChannelHandler) allows to take data +/// from the channel. +/// +/// The channel handler is stored +/// in the Zenoh object (e.g., [`Subscriber`](crate::pubsub::Subscriber)). It can be accessed +/// by [`handler`](crate::pubsub::Subscriber::handler) method or just directly by dereferencing the +/// Zenoh object. pub mod handlers { #[zenoh_macros::internal] pub use crate::api::handlers::locked; @@ -289,6 +346,11 @@ pub mod qos { } /// Scouting primitives +/// +/// Scouting is the process of discovering Zenoh nodes in the network. +/// The scouting process depends on the transport layer and on the zenoh configuration. +/// See more details at . +/// pub mod scouting { pub use zenoh_config::wrappers::Hello; @@ -362,7 +424,17 @@ pub mod time { pub use zenoh_protocol::core::{Timestamp, TimestampId, NTP64}; } -/// Configuration to pass to [`open`] and [`scout`] functions and associated constants +/// Configuration to pass to [`open`] and [`scout`] functions and associated constants. +/// +/// The zenoh configurattion is stored in a JSON file. The [`Config`] can be constructed from it using +/// the corresponding `from_...` methods. It's also possible to read or +/// modify individual elements of the [`Config`] with [`Config::insert_json5`](crate::config::Config::insert_json5) +/// and [`Config::get_json`](crate::config::Config::get_json) methods. +/// +/// The example of the configuration file is +/// [available](https://github.com/eclipse-zenoh/zenoh/blob/release/1.0.0/DEFAULT_CONFIG.json5) +/// in the zenoh repository. +/// pub mod config { pub use zenoh_config::{EndPoint, Locator, WhatAmI, WhatAmIMatcher, ZenohId};