Improve doc

eclipse-zenoh · Dec 10, 2024 · 6332331 · 6332331
1 parent 87acf15
commit 6332331
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 34 deletions.
diff --git a/zenoh-ext/src/advanced_publisher.rs b/zenoh-ext/src/advanced_publisher.rs
@@ -114,16 +114,18 @@ impl<'a, 'b, 'c> AdvancedPublisherBuilder<'a, 'b, 'c> {
         }
     }
 
-    /// Allow matching Subscribers to detect lost samples and optionally ask for retransimission.
+    /// Allow matching [`AdvancedSubscribers`](crate::AdvancedSubscriber) to detect lost samples and optionally ask for retransimission.
     ///
-    /// Retransmission can only be achieved if history is enabled.
+    /// Retransmission can only be achieved if [`cache`](crate::AdvancedPublisherBuilder::cache) is enabled.
     #[zenoh_macros::unstable]
     pub fn sample_miss_detection(mut self) -> Self {
         self.sequencing = Sequencing::SequenceNumber;
         self
     }
 
-    /// Change the history size for each resource.
+    /// Attach a cache to this [`AdvancedPublisher`].
+    ///
+    /// The cache can be used for history and/or recovery.
     #[zenoh_macros::unstable]
     pub fn cache(mut self, config: CacheConfig) -> Self {
         self.cache = true;
@@ -134,9 +136,9 @@ impl<'a, 'b, 'c> AdvancedPublisherBuilder<'a, 'b, 'c> {
         self
     }
 
-    /// Allow this publisher to be detected by subscribers.
+    /// Allow this [`AdvancedPublisher`] to be detected by [`AdvancedSubscribers`](crate::AdvancedSubscriber).
     ///
-    /// This allows Subscribers to retrieve the local history.
+    /// This allows [`AdvancedSubscribers`](crate::AdvancedSubscriber) to retrieve the local history.
     #[zenoh_macros::unstable]
     pub fn publisher_detection(mut self) -> Self {
         self.liveliness = true;

diff --git a/zenoh-ext/src/advanced_subscriber.rs b/zenoh-ext/src/advanced_subscriber.rs
@@ -61,8 +61,8 @@ pub struct HistoryConfig {
 impl HistoryConfig {
     /// Enable detection of late joiner publishers and query for their historical data.
     ///
-    /// Let joiner detection can only be achieved for Publishers that enable publisher_detection.
-    /// History can only be retransmitted by Publishers that enable caching.
+    /// Let joiner detection can only be achieved for [`AdvancedPublishers`](crate::AdvancedPublisher) that enable publisher_detection.
+    /// History can only be retransmitted by [`AdvancedPublishers`](crate::AdvancedPublisher) that enable [`cache`](crate::AdvancedPublisherBuilder::cache).
     #[inline]
     #[zenoh_macros::unstable]
     pub fn detect_late_publishers(mut self) -> Self {
@@ -107,7 +107,9 @@ impl RecoveryConfig {
     /// This allows to retrieve the last Sample(s) if the last Sample(s) is/are lost.
     /// So it is useful for sporadic publications but useless for periodic publications
     /// with a period smaller or equal to this period.
-    /// Retransmission can only be achieved by Publishers that also activate retransmission.
+    /// Retransmission can only be achieved by [`AdvancedPublishers`](crate::AdvancedPublisher)
+    /// that enable [`cache`](crate::AdvancedPublisherBuilder::cache) and
+    /// [`sample_miss_detection`](crate::AdvancedPublisherBuilder::sample_miss_detection).
     #[zenoh_macros::unstable]
     #[inline]
     pub fn periodic_queries(mut self, period: Option<Duration>) -> Self {
@@ -227,8 +229,9 @@ impl<'a, 'c, Handler> AdvancedSubscriberBuilder<'a, '_, 'c, Handler> {
 
     /// Ask for retransmission of detected lost Samples.
     ///
-    /// Retransmission can only be achieved by Publishers that enable
-    /// caching and sample_miss_detection.
+    /// Retransmission can only be achieved by [`AdvancedPublishers`](crate::AdvancedPublisher)
+    /// that enable [`cache`](crate::AdvancedPublisherBuilder::cache) and
+    /// [`sample_miss_detection`](crate::AdvancedPublisherBuilder::sample_miss_detection).
     #[zenoh_macros::unstable]
     #[inline]
     pub fn recovery(mut self, conf: RecoveryConfig) -> Self {
@@ -254,7 +257,7 @@ impl<'a, 'c, Handler> AdvancedSubscriberBuilder<'a, '_, 'c, Handler> {
 
     /// Enable query for historical data.
     ///
-    /// History can only be retransmitted by Publishers that enable caching.
+    /// History can only be retransmitted by [`AdvancedPublishers`](crate::AdvancedPublisher) that enable [`cache`](crate::AdvancedPublisherBuilder::cache).
     #[zenoh_macros::unstable]
     #[inline]
     pub fn history(mut self, config: HistoryConfig) -> Self {
@@ -953,6 +956,10 @@ impl<Handler> AdvancedSubscriber<Handler> {
         &mut self.receiver
     }
 
+    /// Declares a listener to detect missed samples.
+    ///
+    /// Missed samples can only be detected from [`AdvancedPublisher`](crate::AdvancedPublisher) that
+    /// enable [`sample_miss_detection`](crate::AdvancedPublisherBuilder::sample_miss_detection).
     #[zenoh_macros::unstable]
     pub fn sample_miss_listener(&self) -> SampleMissListenerBuilder<'_, DefaultHandler> {
         SampleMissListenerBuilder {
@@ -961,6 +968,10 @@ impl<Handler> AdvancedSubscriber<Handler> {
         }
     }
 
+    /// Declares a listener to detect matching publishers.
+    ///
+    /// Only [`AdvancedPublisher`](crate::AdvancedPublisher) that enable
+    /// [`publisher_detection`](crate::AdvancedPublisherBuilder::publisher_detection) can be detected.
     #[zenoh_macros::unstable]
     pub fn detect_publishers(&self) -> LivelinessSubscriberBuilder<'_, '_, DefaultHandler> {
         self.subscriber.session().liveliness().declare_subscriber(
@@ -1109,21 +1120,29 @@ impl Drop for TimestampedRepliesHandler {
     }
 }
 
+/// A struct that represent missed samples.
 #[zenoh_macros::unstable]
 pub struct Miss {
     source: EntityGlobalId,
     nb: u32,
 }
 
 impl Miss {
+    /// The source of missed samples.
     pub fn source(&self) -> EntityGlobalId {
         self.source
     }
+
+    /// The number of missed samples.
     pub fn nb(&self) -> u32 {
         self.nb
     }
 }
 
+/// A listener to detect missed samples.
+///
+/// Missed samples can only be detected from [`AdvancedPublisher`](crate::AdvancedPublisher) that
+/// enable [`sample_miss_detection`](crate::AdvancedPublisherBuilder::sample_miss_detection).
 #[zenoh_macros::unstable]
 pub struct SampleMissListener<Handler> {
     id: usize,
@@ -1182,6 +1201,7 @@ impl<Handler> std::ops::DerefMut for SampleMissListener<Handler> {
     }
 }
 
+/// A [`Resolvable`] returned when undeclaring a [`SampleMissListener`].
 #[zenoh_macros::unstable]
 pub struct SampleMissHandlerUndeclaration<Handler>(SampleMissListener<Handler>);
 
@@ -1207,7 +1227,7 @@ impl<Handler> IntoFuture for SampleMissHandlerUndeclaration<Handler> {
     }
 }
 
-/// A builder for initializing a [`SampleMissHandler`].
+/// A builder for initializing a [`SampleMissListener`].
 #[zenoh_macros::unstable]
 pub struct SampleMissListenerBuilder<'a, Handler, const BACKGROUND: bool = false> {
     statesref: &'a Arc<Mutex<State>>,

diff --git a/zenoh-ext/src/publisher_ext.rs b/zenoh-ext/src/publisher_ext.rs
@@ -18,22 +18,20 @@ use crate::{advanced_cache::CacheConfig, AdvancedPublisherBuilder};
 /// Some extensions to the [`zenoh::publication::PublisherBuilder`](zenoh::publication::PublisherBuilder)
 #[zenoh_macros::unstable]
 pub trait AdvancedPublisherBuilderExt<'a, 'b, 'c> {
-    /// Allow matching Subscribers to detect lost samples and
-    /// optionally ask for retransimission.
-    ///
-    /// Retransmission can only be achieved if history is enabled.
+    /// Allow matching [`AdvancedSubscribers`](crate::AdvancedSubscriber) to recover history and/or missed samples.
     #[zenoh_macros::unstable]
     fn cache(self, config: CacheConfig) -> AdvancedPublisherBuilder<'a, 'b, 'c>;
 
-    /// Allow matching Subscribers to detect lost samples and optionally ask for retransimission.
+    /// Allow matching [`AdvancedSubscribers`](crate::AdvancedSubscriber) to detect lost samples
+    /// and optionally ask for retransimission.
     ///
-    /// Retransmission can only be achieved if cache is enabled.
+    /// Retransmission can only be achieved if [`cache`](crate::AdvancedPublisherBuilder::cache) is also enabled.
     #[zenoh_macros::unstable]
     fn sample_miss_detection(self) -> AdvancedPublisherBuilder<'a, 'b, 'c>;
 
-    /// Allow this publisher to be detected by subscribers.
+    /// Allow this publisher to be detected by [`AdvancedSubscribers`](crate::AdvancedSubscriber).
     ///
-    /// This allows Subscribers to retrieve the local history.
+    /// This allows [`AdvancedSubscribers`](crate::AdvancedSubscriber) to retrieve the local history.
     #[zenoh_macros::unstable]
     fn publisher_detection(self) -> AdvancedPublisherBuilder<'a, 'b, 'c>;
 
@@ -44,26 +42,24 @@ pub trait AdvancedPublisherBuilderExt<'a, 'b, 'c> {
 
 #[zenoh_macros::unstable]
 impl<'a, 'b, 'c> AdvancedPublisherBuilderExt<'a, 'b, 'c> for PublisherBuilder<'a, 'b> {
-    /// Allow matching Subscribers to detect lost samples and
-    /// optionally ask for retransimission.
-    ///
-    /// Retransmission can only be achieved if history is enabled.
+    /// Allow matching [`AdvancedSubscribers`](crate::AdvancedSubscriber) to recover history and/or missed samples.
     #[zenoh_macros::unstable]
     fn cache(self, config: CacheConfig) -> AdvancedPublisherBuilder<'a, 'b, 'c> {
         AdvancedPublisherBuilder::new(self).cache(config)
     }
 
-    /// Allow matching Subscribers to detect lost samples and optionally ask for retransimission.
+    /// Allow matching [`AdvancedSubscribers`](crate::AdvancedSubscriber) to detect lost samples
+    /// and optionally ask for retransimission.
     ///
-    /// Retransmission can only be achieved if cache is enabled.
+    /// Retransmission can only be achieved if [`cache`](crate::AdvancedPublisherBuilder::cache) is also enabled.
     #[zenoh_macros::unstable]
     fn sample_miss_detection(self) -> AdvancedPublisherBuilder<'a, 'b, 'c> {
         AdvancedPublisherBuilder::new(self).sample_miss_detection()
     }
 
-    /// Allow this publisher to be detected by subscribers.
+    /// Allow this publisher to be detected by [`AdvancedSubscribers`](crate::AdvancedSubscriber).
     ///
-    /// This allows Subscribers to retrieve the local history.
+    /// This allows [`AdvancedSubscribers`](crate::AdvancedSubscriber) to retrieve the local history.
     #[zenoh_macros::unstable]
     fn publisher_detection(self) -> AdvancedPublisherBuilder<'a, 'b, 'c> {
         AdvancedPublisherBuilder::new(self).publisher_detection()

diff --git a/zenoh-ext/src/subscriber_ext.rs b/zenoh-ext/src/subscriber_ext.rs
@@ -137,14 +137,15 @@ pub trait SubscriberBuilderExt<'a, 'b, Handler> {
 pub trait AdvancedSubscriberBuilderExt<'a, 'b, 'c, Handler> {
     /// Enable query for historical data.
     ///
-    /// History can only be retransmitted by Publishers that enable caching.
+    /// History can only be retransmitted by [`AdvancedPublishers`](crate::AdvancedPublisher) that enable [`cache`](crate::AdvancedPublisherBuilder::cache).
     #[zenoh_macros::unstable]
     fn history(self, config: HistoryConfig) -> AdvancedSubscriberBuilder<'a, 'b, 'c, Handler>;
 
     /// Ask for retransmission of detected lost Samples.
     ///
-    /// Retransmission can only be achieved by Publishers that enable
-    /// caching and sample_miss_detection.
+    /// Retransmission can only be achieved by [`AdvancedPublishers`](crate::AdvancedPublisher)
+    /// that enable [`cache`](crate::AdvancedPublisherBuilder::cache) and
+    /// [`sample_miss_detection`](crate::AdvancedPublisherBuilder::sample_miss_detection).
     #[zenoh_macros::unstable]
     fn recovery(self, conf: RecoveryConfig) -> AdvancedSubscriberBuilder<'a, 'b, 'c, Handler>;
 
@@ -271,16 +272,17 @@ impl<'a, 'b, 'c, Handler> AdvancedSubscriberBuilderExt<'a, 'b, 'c, Handler>
 {
     /// Enable query for historical data.
     ///
-    /// History can only be retransmitted by Publishers that enable caching.
+    /// History can only be retransmitted by [`AdvancedPublishers`](crate::AdvancedPublisher) that enable [`cache`](crate::AdvancedPublisherBuilder::cache).
     #[zenoh_macros::unstable]
     fn history(self, config: HistoryConfig) -> AdvancedSubscriberBuilder<'a, 'b, 'c, Handler> {
         AdvancedSubscriberBuilder::new(self).history(config)
     }
 
     /// Ask for retransmission of detected lost Samples.
     ///
-    /// Retransmission can only be achieved by Publishers that enable
-    /// caching and sample_miss_detection.
+    /// Retransmission can only be achieved by [`AdvancedPublishers`](crate::AdvancedPublisher)
+    /// that enable [`cache`](crate::AdvancedPublisherBuilder::cache) and
+    /// [`sample_miss_detection`](crate::AdvancedPublisherBuilder::sample_miss_detection).
     #[zenoh_macros::unstable]
     fn recovery(self, conf: RecoveryConfig) -> AdvancedSubscriberBuilder<'a, 'b, 'c, Handler> {
         AdvancedSubscriberBuilder::new(self).recovery(conf)