log, handler doc update

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: <https://github.com/tokio-rs/tracing/issues/2069>
 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: <https://github.com/tokio-rs/tracing/issues/2069>
 pub fn init_log_from_env_or<S>(fallback: S)

zenoh/src/api/handlers/mod.rs

@@ -13,6 +13,16 @@
 //
 
 //! Callback handler trait.
+//! 
+//! The zenoh primitives which receive data (e.g. [`Subscriber`](crate::pubsub::Subscriber), [`Query`](crate::query::Query), etc.) accept in their [`with()`](crate::pubsub::SubscriberBuilder::with) method a handler 
+//! which processes received message. The handler is actually a pair of a [`Callback`] and a handler. The callback is called on each received message, the handler is an object of arbitrary type, which can be used to access
+//! the data received by callback. When the handler is not needed, the handler type can be `()`. This particular case is handled by the [`callback()`](crate::pubsub::SubscriberBuilder::callback) method which directly accepts a `Fn(T)`.
+//! 
+//! The [`with()`](crate::pubsub::SubscriberBuilder::with) method accepts any type that implements the [`IntoHandler`] trait which in turn provides a conversion to a pair of [`Callback`] and handler.
+//! 
+//! The channels [`FifoChannel`] and [`RingChannel`] provided by zenoh implements the [`IntoHandler`] trait which returns a pair of [`Callback`] which pushes the data to the channel and the receiving channel's end [`FifoChannelHandler`] or [`RingChannelHandler`] 
+//! correspondingly. This receiving end is stored in the constructed zenoh object (e.g[`Subscriber`](crate::pubsub::Subscriber)) and its methods can be accessed directly on this object, as it implements the 
+//! [`Deref`](std::ops::Deref) and [`DerefMut`](std::ops::DerefMut) traits for the handler type.
 mod callback;
 mod fifo;
 mod ring;