From 4bb414d80c44a0e5c43a0d694c7e807376a71a39 Mon Sep 17 00:00:00 2001 From: Michael Ilyin Date: Wed, 7 Feb 2024 17:57:06 +0100 Subject: [PATCH] tags added --- zenoh/src/handlers.rs | 4 ++++ zenoh/src/info.rs | 7 +++++++ zenoh/src/key_expr.rs | 14 +++++++++++++ zenoh/src/lib.rs | 15 ++++++++++++-- zenoh/src/liveliness.rs | 17 +++++++++++++++ zenoh/src/net/mod.rs | 6 ++++++ zenoh/src/publication.rs | 45 ++++++++++++++++++++++++++++++++++++++++ zenoh/src/query.rs | 20 ++++++++++++++++++ zenoh/src/queryable.rs | 19 +++++++++++++++++ zenoh/src/sample.rs | 39 ++++++++++++++++++++++++++++++++++ zenoh/src/scouting.rs | 7 +++++++ zenoh/src/selector.rs | 22 ++++++++++++++++++++ zenoh/src/session.rs | 20 ++++++++++++++++++ zenoh/src/subscriber.rs | 22 ++++++++++++++++++++ zenoh/src/value.rs | 3 +++ 15 files changed, 258 insertions(+), 2 deletions(-) diff --git a/zenoh/src/handlers.rs b/zenoh/src/handlers.rs index 69828a5d7f..bef7b9a269 100644 --- a/zenoh/src/handlers.rs +++ b/zenoh/src/handlers.rs @@ -26,6 +26,7 @@ pub type Callback<'a, T> = Dyn; /// while granting you access to the receiver through the returned value via [`std::ops::Deref`] and [`std::ops::DerefMut`]. /// /// Any closure that accepts `T` can be converted into a pair of itself and `()`. +// tags{} pub trait IntoCallbackReceiverPair<'a, T> { type Receiver; fn into_cb_receiver_pair(self) -> (Callback<'a, T>, Self::Receiver); @@ -56,6 +57,7 @@ impl IntoCallbackReceiverPair<'static, T> ) } } +// tags{} pub struct DefaultHandler; impl IntoCallbackReceiverPair<'static, T> for DefaultHandler { type Receiver = flume::Receiver; @@ -82,6 +84,7 @@ impl IntoCallbackReceiverPair<'static, T> /// A function that can transform a [`FnMut`]`(T)` to /// a [`Fn`]`(T)` with the help of a [`Mutex`](std::sync::Mutex). +// tags{} pub fn locked(fnmut: impl FnMut(T)) -> impl Fn(T) { let lock = std::sync::Mutex::new(fnmut); move |x| zlock!(lock)(x) @@ -96,6 +99,7 @@ pub fn locked(fnmut: impl FnMut(T)) -> impl Fn(T) { /// - `callback` will never be called once `drop` has started. /// - `drop` will only be called **once**, and **after every** `callback` has ended. /// - The two previous guarantees imply that `call` and `drop` are never called concurrently. +// tags{} pub struct CallbackPair where DropFn: FnMut() + Send + Sync + 'static, diff --git a/zenoh/src/info.rs b/zenoh/src/info.rs index 848a5cb68b..eae640098d 100644 --- a/zenoh/src/info.rs +++ b/zenoh/src/info.rs @@ -31,6 +31,7 @@ use zenoh_protocol::core::{WhatAmI, ZenohId}; /// let zid = session.info().zid().res().await; /// # }) /// ``` +// tags{} #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct ZidBuilder<'a> { @@ -69,6 +70,7 @@ impl<'a> AsyncResolve for ZidBuilder<'a> { /// while let Some(router_zid) = routers_zid.next() {} /// # }) /// ``` +// tags{} #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct RoutersZidBuilder<'a> { @@ -116,6 +118,7 @@ impl<'a> AsyncResolve for RoutersZidBuilder<'a> { /// while let Some(peer_zid) = peers_zid.next() {} /// # }) /// ``` +// tags{} #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct PeersZidBuilder<'a> { @@ -162,6 +165,7 @@ impl<'a> AsyncResolve for PeersZidBuilder<'a> { /// let zid = info.zid().res().await; /// # }) /// ``` +// tags{} pub struct SessionInfo<'a> { pub(crate) session: SessionRef<'a>, } @@ -178,6 +182,7 @@ impl SessionInfo<'_> { /// let zid = session.info().zid().res().await; /// # }) /// ``` + // tags{session.zid.get} pub fn zid(&self) -> ZidBuilder<'_> { ZidBuilder { session: self.session.clone(), @@ -197,6 +202,7 @@ impl SessionInfo<'_> { /// while let Some(router_zid) = routers_zid.next() {} /// # }) /// ``` + // tags{session.routers_zid.get} pub fn routers_zid(&self) -> RoutersZidBuilder<'_> { RoutersZidBuilder { session: self.session.clone(), @@ -215,6 +221,7 @@ impl SessionInfo<'_> { /// while let Some(peer_zid) = peers_zid.next() {} /// # }) /// ``` + // tags{session.peers_zid.get} pub fn peers_zid(&self) -> PeersZidBuilder<'_> { PeersZidBuilder { session: self.session.clone(), diff --git a/zenoh/src/key_expr.rs b/zenoh/src/key_expr.rs index d2295f9798..185379acd8 100644 --- a/zenoh/src/key_expr.rs +++ b/zenoh/src/key_expr.rs @@ -52,6 +52,7 @@ pub(crate) enum KeyExprInner<'a> { /// A possibly-owned version of [`keyexpr`] that may carry optimisations for use with a [`Session`] that may have declared it. /// /// Check [`keyexpr`]'s documentation for detailed explainations of the Key Expression Language. +// tags{keyexpr} #[repr(transparent)] #[derive(Clone, serde::Deserialize, serde::Serialize)] #[serde(from = "OwnedKeyExpr")] @@ -74,6 +75,7 @@ impl KeyExpr<'static> { /// # Safety /// Key Expressions must follow some rules to be accepted by a Zenoh network. /// Messages addressed with invalid key expressions will be dropped. + // tags{keyexpr.create.from_string_unchecked} pub unsafe fn from_string_unchecked(s: String) -> Self { Self(KeyExprInner::Owned(OwnedKeyExpr::from_string_unchecked(s))) } @@ -82,6 +84,7 @@ impl KeyExpr<'static> { /// # Safety /// Key Expressions must follow some rules to be accepted by a Zenoh network. /// Messages addressed with invalid key expressions will be dropped. + // tags{keyexpr.create.from_string_unchecked} pub unsafe fn from_boxed_string_unchecked(s: Box) -> Self { Self(KeyExprInner::Owned( OwnedKeyExpr::from_boxed_string_unchecked(s), @@ -95,6 +98,7 @@ impl<'a> KeyExpr<'a> { /// Note that to be considered a valid key expression, a string MUST be canon. /// /// [`KeyExpr::autocanonize`] is an alternative constructor that will canonize the passed expression before constructing it. + // tags{keyexpr.create} pub fn new(t: T) -> Result where Self: TryFrom, @@ -105,6 +109,7 @@ impl<'a> KeyExpr<'a> { /// Constructs a new [`KeyExpr`] aliasing `self`. /// /// Note that [`KeyExpr`] (as well as [`OwnedKeyExpr`]) use reference counters internally, so you're probably better off using clone. + // tags{} pub fn borrowing_clone(&'a self) -> Self { let inner = match &self.0 { KeyExprInner::Borrowed(key_expr) => KeyExprInner::Borrowed(key_expr), @@ -142,6 +147,7 @@ impl<'a> KeyExpr<'a> { /// Canonizes the passed value before returning it as a `KeyExpr`. /// /// Will return Err if the passed value isn't a valid key expression despite canonization. + // tags{keyexpr.autocanonize} pub fn autocanonize(mut t: T) -> Result where Self: TryFrom, @@ -155,16 +161,19 @@ impl<'a> KeyExpr<'a> { /// # Safety /// Key Expressions must follow some rules to be accepted by a Zenoh network. /// Messages addressed with invalid key expressions will be dropped. + // tags{keyexpr.create.from_string_unchecked} pub unsafe fn from_str_uncheckend(s: &'a str) -> Self { keyexpr::from_str_unchecked(s).into() } /// Returns the borrowed version of `self` + // tags{} pub fn as_keyexpr(&self) -> &keyexpr { self } /// Ensures `self` owns all of its data, and informs rustc that it does. + // tags{} pub fn into_owned(self) -> KeyExpr<'static> { match self.0 { KeyExprInner::Borrowed(s) => KeyExpr(KeyExprInner::Owned(s.into())), @@ -210,6 +219,7 @@ impl<'a> KeyExpr<'a> { /// let workspace: KeyExpr = get_workspace(); /// let topic = workspace.join("some/topic").unwrap(); /// ``` + // tags{keyexpr.join} pub fn join + ?Sized>(&self, s: &S) -> ZResult> { let r = self.as_keyexpr().join(s)?; if let KeyExprInner::Wire { @@ -235,6 +245,7 @@ impl<'a> KeyExpr<'a> { /// Performs string concatenation and returns the result as a [`KeyExpr`] if possible. /// /// You should probably prefer [`KeyExpr::join`] as Zenoh may then take advantage of the hierachical separation it inserts. + // tags{keyexpr.concat} pub fn concat + ?Sized>(&self, s: &S) -> ZResult> { let s = s.as_ref(); self._concat(s) @@ -272,6 +283,7 @@ impl<'a> KeyExpr<'a> { } } + // tags{selector.create.from_keyexpr} pub fn with_parameters(self, selector: &'a str) -> Selector<'a> { Selector { key_expr: self, @@ -279,6 +291,7 @@ impl<'a> KeyExpr<'a> { } } + // tags{selector.create.from_keyexpr} pub fn with_owned_parameters(self, selector: String) -> Selector<'a> { Selector { key_expr: self, @@ -584,6 +597,7 @@ impl<'a> Undeclarable<&'a Session, KeyExprUndeclaration<'a>> for KeyExpr<'a> { /// session.undeclare(key_expr).res().await.unwrap(); /// # }) /// ``` +// tags{} #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct KeyExprUndeclaration<'a> { session: &'a Session, diff --git a/zenoh/src/lib.rs b/zenoh/src/lib.rs index 5c3b938e5b..a01babde32 100644 --- a/zenoh/src/lib.rs +++ b/zenoh/src/lib.rs @@ -99,6 +99,7 @@ pub use zenoh_result::ZResult as Result; const GIT_VERSION: &str = git_version!(prefix = "v", cargo_prefix = "v"); +// tags{} pub const FEATURES: &str = concat_enabled_features!( prefix = "zenoh", features = [ @@ -136,6 +137,7 @@ pub mod handlers; pub mod info; #[cfg(feature = "unstable")] pub mod liveliness; +// ignore_tagging pub mod plugins; pub mod prelude; pub mod publication; @@ -160,6 +162,7 @@ pub mod time { /// Generates a reception [`Timestamp`] with id=0x01. /// This operation should be called if a timestamp is required for an incoming [`zenoh::Sample`](crate::Sample) /// that doesn't contain any timestamp. + // tags{timestamp.create} pub fn new_reception_timestamp() -> Timestamp { use std::time::{SystemTime, UNIX_EPOCH}; @@ -173,9 +176,10 @@ pub mod properties { use super::prelude::Value; pub use zenoh_collections::Properties; - /// Convert a set of [`Properties`] into a [`Value`]. - /// For instance, Properties: `[("k1", "v1"), ("k2, v2")]` + /// Convert a set of [`Properties`] into a [`Value`]. + /// For instance, Properties: `[("k1", "v1"), ("k2, v2")]` /// is converted into Json: `{ "k1": "v1", "k2": "v2" }` + // tags{value.create.from_properties} pub fn properties_to_json_value(props: &Properties) -> Value { let json_map = props .iter() @@ -214,6 +218,7 @@ pub mod scouting; /// } /// # }) /// ``` +/// tags{scout} pub fn scout, TryIntoConfig>( what: I, config: TryIntoConfig, @@ -257,6 +262,7 @@ where /// let session = zenoh::open(config).res().await.unwrap(); /// # }) /// ``` +// tags{session.create} pub fn open(config: TryIntoConfig) -> OpenBuilder where TryIntoConfig: std::convert::TryInto + Send + 'static, @@ -275,6 +281,7 @@ where /// let session = zenoh::open(config::peer()).res().await.unwrap(); /// # }) /// ``` +// tags{} #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct OpenBuilder where @@ -322,6 +329,7 @@ where /// This operation is used by the plugins to share the same Runtime as the router. #[doc(hidden)] #[zenoh_macros::unstable] +// tags{} pub fn init(runtime: Runtime) -> InitBuilder { InitBuilder { runtime, @@ -334,6 +342,7 @@ pub fn init(runtime: Runtime) -> InitBuilder { #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[doc(hidden)] #[zenoh_macros::unstable] +// tags{} pub struct InitBuilder { runtime: Runtime, aggregated_subscribers: Vec, @@ -343,12 +352,14 @@ pub struct InitBuilder { #[zenoh_macros::unstable] impl InitBuilder { #[inline] + // tags{} pub fn aggregated_subscribers(mut self, exprs: Vec) -> Self { self.aggregated_subscribers = exprs; self } #[inline] + // tags{} pub fn aggregated_publishers(mut self, exprs: Vec) -> Self { self.aggregated_publishers = exprs; self diff --git a/zenoh/src/liveliness.rs b/zenoh/src/liveliness.rs index 0883041bb7..efe4c3c2bc 100644 --- a/zenoh/src/liveliness.rs +++ b/zenoh/src/liveliness.rs @@ -76,6 +76,7 @@ lazy_static::lazy_static!( /// .unwrap(); /// # }) /// ``` +// tags{liveliness} #[zenoh_macros::unstable] pub struct Liveliness<'a> { pub(crate) session: SessionRef<'a>, @@ -103,6 +104,7 @@ impl<'a> Liveliness<'a> { /// .unwrap(); /// # }) /// ``` + // tags{liveliness.token.create} #[zenoh_macros::unstable] pub fn declare_token<'b, TryIntoKeyExpr>( &self, @@ -139,6 +141,7 @@ impl<'a> Liveliness<'a> { /// } /// # }) /// ``` + // tags{liveliness.subscriber.create} #[zenoh_macros::unstable] pub fn declare_subscriber<'b, TryIntoKeyExpr>( &self, @@ -175,6 +178,7 @@ impl<'a> Liveliness<'a> { /// } /// # }) /// ``` + // tags{liveliness.query_token} #[zenoh_macros::unstable] pub fn get<'b: 'a, TryIntoKeyExpr>( &'a self, @@ -217,6 +221,7 @@ impl<'a> Liveliness<'a> { #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[zenoh_macros::unstable] #[derive(Debug)] +// tags{} pub struct LivelinessTokenBuilder<'a, 'b> { pub(crate) session: SessionRef<'a>, pub(crate) key_expr: ZResult>, @@ -290,6 +295,7 @@ pub(crate) struct LivelinessTokenState { /// ``` #[zenoh_macros::unstable] #[derive(Debug)] +// tags{liveliness.token} pub struct LivelinessToken<'a> { pub(crate) session: SessionRef<'a>, pub(crate) state: Arc, @@ -316,6 +322,7 @@ pub struct LivelinessToken<'a> { /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[zenoh_macros::unstable] +// tags{} pub struct LivelinessTokenUndeclaration<'a> { token: LivelinessToken<'a>, } @@ -367,6 +374,7 @@ impl<'a> LivelinessToken<'a> { /// # }) /// ``` #[inline] + // tags{} pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self, ()) } @@ -408,6 +416,7 @@ impl Drop for LivelinessToken<'_> { #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[zenoh_macros::unstable] #[derive(Debug)] +// tags{} pub struct LivelinessSubscriberBuilder<'a, 'b, Handler> { pub session: SessionRef<'a>, pub key_expr: ZResult>, @@ -434,6 +443,7 @@ impl<'a, 'b> LivelinessSubscriberBuilder<'a, 'b, DefaultHandler> { /// ``` #[inline] #[zenoh_macros::unstable] + // tags{live.subscriber.callback} pub fn callback( self, callback: Callback, @@ -475,6 +485,7 @@ impl<'a, 'b> LivelinessSubscriberBuilder<'a, 'b, DefaultHandler> { /// ``` #[inline] #[zenoh_macros::unstable] + // tags{live.subscriber.callback} pub fn callback_mut( self, callback: CallbackMut, @@ -506,6 +517,7 @@ impl<'a, 'b> LivelinessSubscriberBuilder<'a, 'b, DefaultHandler> { /// ``` #[inline] #[zenoh_macros::unstable] + // tags{live.subscriber.pipe} pub fn with(self, handler: Handler) -> LivelinessSubscriberBuilder<'a, 'b, Handler> where Handler: crate::prelude::IntoCallbackReceiverPair<'static, Sample>, @@ -602,6 +614,7 @@ where /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] +// tags{} pub struct LivelinessGetBuilder<'a, 'b, Handler> { pub(crate) session: &'a Session, pub(crate) key_expr: ZResult>, @@ -627,6 +640,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{liveliness.query_token.callback} #[inline] pub fn callback(self, callback: Callback) -> LivelinessGetBuilder<'a, 'b, Callback> where @@ -668,6 +682,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{liveliness.query_token.callback} pub fn callback_mut( self, callback: CallbackMut, @@ -699,6 +714,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{liveliness.query_token.pipe} pub fn with(self, handler: Handler) -> LivelinessGetBuilder<'a, 'b, Handler> where Handler: IntoCallbackReceiverPair<'static, Reply>, @@ -721,6 +737,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { impl<'a, 'b, Handler> LivelinessGetBuilder<'a, 'b, Handler> { /// Set query timeout. #[inline] + // tags{liveliness.query_token.timeout} pub fn timeout(mut self, timeout: Duration) -> Self { self.timeout = timeout; self diff --git a/zenoh/src/net/mod.rs b/zenoh/src/net/mod.rs index 346426a630..9e35feb77c 100644 --- a/zenoh/src/net/mod.rs +++ b/zenoh/src/net/mod.rs @@ -18,15 +18,21 @@ //! //! [Click here for Zenoh's documentation](../zenoh/index.html) #[doc(hidden)] +// ignore_tagging pub(crate) mod codec; #[doc(hidden)] +// ignore_tagging pub(crate) mod primitives; #[doc(hidden)] +// ignore_tagging pub(crate) mod protocol; #[doc(hidden)] +// ignore_tagging pub(crate) mod routing; #[doc(hidden)] +// ignore_tagging pub mod runtime; #[cfg(test)] +// ignore_tagging pub(crate) mod tests; diff --git a/zenoh/src/publication.rs b/zenoh/src/publication.rs index 843190ad45..279a0a16d8 100644 --- a/zenoh/src/publication.rs +++ b/zenoh/src/publication.rs @@ -76,6 +76,7 @@ pub type DeleteBuilder<'a, 'b> = PutBuilder<'a, 'b>; /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug, Clone)] +// tags{session.put} pub struct PutBuilder<'a, 'b> { pub(crate) publisher: PublisherBuilder<'a, 'b>, pub(crate) value: Value, @@ -87,6 +88,7 @@ pub struct PutBuilder<'a, 'b> { impl PutBuilder<'_, '_> { /// Change the encoding of the written data. #[inline] + // tags{session.put.encoding.set} pub fn encoding(mut self, encoding: IntoEncoding) -> Self where IntoEncoding: Into, @@ -96,6 +98,7 @@ impl PutBuilder<'_, '_> { } /// Change the `congestion_control` to apply when routing the data. #[inline] + // tags{session.put.encoding.congestion_control.set} pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.publisher = self.publisher.congestion_control(congestion_control); self @@ -103,6 +106,7 @@ impl PutBuilder<'_, '_> { /// Change the priority of the written data. #[inline] + // tags{session.put.encoding.priority.set} pub fn priority(mut self, priority: Priority) -> Self { self.publisher = self.publisher.priority(priority); self @@ -112,17 +116,20 @@ impl PutBuilder<'_, '_> { /// to the ones that have the given [`Locality`](crate::prelude::Locality). #[zenoh_macros::unstable] #[inline] + // tags{session.put.allowed_destination.set} pub fn allowed_destination(mut self, destination: Locality) -> Self { self.publisher = self.publisher.allowed_destination(destination); self } + // tags{session.put.kind.set} pub fn kind(mut self, kind: SampleKind) -> Self { self.kind = kind; self } #[zenoh_macros::unstable] + // tags{session.put.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self @@ -179,6 +186,7 @@ use zenoh_result::Error; #[zenoh_macros::unstable] #[derive(Clone)] +// tags{} pub enum PublisherRef<'a> { Borrow(&'a Publisher<'a>), Shared(std::sync::Arc>), @@ -236,6 +244,7 @@ impl std::fmt::Debug for PublisherRef<'_> { /// # }) /// ``` #[derive(Debug, Clone)] +// tags{publisher} pub struct Publisher<'a> { pub(crate) session: SessionRef<'a>, pub(crate) key_expr: KeyExpr<'a>, @@ -245,12 +254,15 @@ pub struct Publisher<'a> { } impl<'a> Publisher<'a> { + /// Get key expression of the publisher. + // tags{publisher.key_expr.get} pub fn key_expr(&self) -> &KeyExpr<'a> { &self.key_expr } /// Change the `congestion_control` to apply when routing the data. #[inline] + // tags{publisher.congestion_control.set} pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.congestion_control = congestion_control; self @@ -258,6 +270,7 @@ impl<'a> Publisher<'a> { /// Change the priority of the written data. #[inline] + // tags{publisher.priority.set} pub fn priority(mut self, priority: Priority) -> Self { self.priority = priority; self @@ -267,6 +280,7 @@ impl<'a> Publisher<'a> { /// to the ones that have the given [`Locality`](crate::prelude::Locality). #[zenoh_macros::unstable] #[inline] + // tags{publisher.allowed_destination.set} pub fn allowed_destination(mut self, destination: Locality) -> Self { self.destination = destination; self @@ -303,6 +317,7 @@ impl<'a> Publisher<'a> { /// # }) /// ``` #[zenoh_macros::unstable] + // tags{} pub fn into_arc(self) -> std::sync::Arc { std::sync::Arc::new(self) } @@ -329,6 +344,7 @@ impl<'a> Publisher<'a> { /// publisher.write(SampleKind::Put, "value").res().await.unwrap(); /// # }) /// ``` + // tags{publisher.write} pub fn write(&self, kind: SampleKind, value: IntoValue) -> Publication where IntoValue: Into, @@ -349,6 +365,7 @@ impl<'a> Publisher<'a> { /// # }) /// ``` #[inline] + // tags{publisher.write.put} pub fn put(&self, value: IntoValue) -> Publication where IntoValue: Into, @@ -368,6 +385,7 @@ impl<'a> Publisher<'a> { /// publisher.delete().res().await.unwrap(); /// # }) /// ``` + // tags{publisher.write.delete} pub fn delete(&self) -> Publication { self._write(SampleKind::Delete, Value::empty()) } @@ -393,6 +411,7 @@ impl<'a> Publisher<'a> { /// # }) /// ``` #[zenoh_macros::unstable] + // tags{publisher.matching_status.get} pub fn matching_status(&self) -> impl Resolve> + '_ { zenoh_core::ResolveFuture::new(async move { self.session @@ -423,6 +442,7 @@ impl<'a> Publisher<'a> { /// # }) /// ``` #[zenoh_macros::unstable] + // tags{publisher.matching_listener.create} pub fn matching_listener(&self) -> MatchingListenerBuilder<'_, DefaultHandler> { MatchingListenerBuilder { publisher: PublisherRef::Borrow(self), @@ -442,6 +462,7 @@ impl<'a> Publisher<'a> { /// publisher.undeclare().res().await.unwrap(); /// # }) /// ``` + // tags{publisher.undeclare} pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self, ()) } @@ -476,6 +497,7 @@ impl<'a> Publisher<'a> { /// # }) /// ``` #[zenoh_macros::unstable] +// tag{} pub trait PublisherDeclarations { /// # Examples /// ```no_run @@ -498,6 +520,7 @@ pub trait PublisherDeclarations { /// # }) /// ``` #[zenoh_macros::unstable] + // tags{publisher.matching_listener.create} fn matching_listener(&self) -> MatchingListenerBuilder<'static, DefaultHandler>; } @@ -524,6 +547,7 @@ impl PublisherDeclarations for std::sync::Arc> { /// # }) /// ``` #[zenoh_macros::unstable] + // tags{publisher.matching_listener.create} fn matching_listener(&self) -> MatchingListenerBuilder<'static, DefaultHandler> { MatchingListenerBuilder { publisher: PublisherRef::Shared(self.clone()), @@ -551,6 +575,7 @@ impl<'a> Undeclarable<(), PublisherUndeclaration<'a>> for Publisher<'a> { /// # }) /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] +// tags{} pub struct PublisherUndeclaration<'a> { publisher: Publisher<'a>, } @@ -594,6 +619,7 @@ impl Drop for Publisher<'_> { /// A [`Resolvable`] returned by [`Publisher::put()`](Publisher::put), /// [`Publisher::delete()`](Publisher::delete) and [`Publisher::write()`](Publisher::write). #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] +// tags{} pub struct Publication<'a> { publisher: &'a Publisher<'a>, value: Value, @@ -603,6 +629,7 @@ pub struct Publication<'a> { } impl<'a> Publication<'a> { + // tags{publisher.write.attachment.set} #[zenoh_macros::unstable] pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); @@ -680,6 +707,7 @@ where /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] +// tags{} pub struct PublisherBuilder<'a, 'b: 'a> { pub(crate) session: SessionRef<'a>, pub(crate) key_expr: ZResult>, @@ -706,6 +734,7 @@ impl<'a, 'b> Clone for PublisherBuilder<'a, 'b> { impl<'a, 'b> PublisherBuilder<'a, 'b> { /// Change the `congestion_control` to apply when routing the data. #[inline] + // tags{publisher.congestion_control.set} pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.congestion_control = congestion_control; self @@ -713,6 +742,7 @@ impl<'a, 'b> PublisherBuilder<'a, 'b> { /// Change the priority of the written data. #[inline] + // tags{publisher.priority.set} pub fn priority(mut self, priority: Priority) -> Self { self.priority = priority; self @@ -722,6 +752,7 @@ impl<'a, 'b> PublisherBuilder<'a, 'b> { /// to the ones that have the given [`Locality`](crate::prelude::Locality). #[zenoh_macros::unstable] #[inline] + // tags{publisher.allowed_destination.set} pub fn allowed_destination(mut self, destination: Locality) -> Self { self.destination = destination; self @@ -875,6 +906,7 @@ fn resolve_put( /// The Priority of zenoh messages. #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] +// tags{publisher.options.priority} pub enum Priority { RealTime = 1, InteractiveHigh = 2, @@ -888,10 +920,13 @@ pub enum Priority { impl Priority { /// The lowest Priority + // tags{publisher.options.priority.min} pub const MIN: Self = Self::Background; /// The highest Priority + // tags{publisher.options.priority.max} pub const MAX: Self = Self::RealTime; /// The number of available priorities + // tags{publisher.options.priority.num} pub const NUM: usize = 1 + Self::MIN as usize - Self::MAX as usize; } @@ -953,6 +988,7 @@ impl From for zenoh_protocol::core::Priority { /// ``` #[zenoh_macros::unstable] #[derive(Copy, Clone, Debug)] +// tags{options.publisher.matching_status} pub struct MatchingStatus { pub(crate) matching: bool, } @@ -976,6 +1012,7 @@ impl MatchingStatus { /// .matching_subscribers(); /// # }) /// ``` + // tags{options.publisher.matching_status.matching_subscribers} pub fn matching_subscribers(&self) -> bool { self.matching } @@ -984,6 +1021,7 @@ impl MatchingStatus { /// A builder for initializing a [`MatchingListener`]. #[zenoh_macros::unstable] #[derive(Debug)] +// tags{publisher.matching_listener} pub struct MatchingListenerBuilder<'a, Handler> { pub(crate) publisher: PublisherRef<'a>, pub handler: Handler, @@ -1016,6 +1054,7 @@ impl<'a> MatchingListenerBuilder<'a, DefaultHandler> { /// ``` #[inline] #[zenoh_macros::unstable] + // tags{publisher.matching_listener.callback} pub fn callback(self, callback: Callback) -> MatchingListenerBuilder<'a, Callback> where Callback: Fn(MatchingStatus) + Send + Sync + 'static, @@ -1050,6 +1089,7 @@ impl<'a> MatchingListenerBuilder<'a, DefaultHandler> { /// ``` #[inline] #[zenoh_macros::unstable] + // tags{publisher.matching_listener.callback} pub fn callback_mut( self, callback: CallbackMut, @@ -1086,6 +1126,7 @@ impl<'a> MatchingListenerBuilder<'a, DefaultHandler> { /// ``` #[inline] #[zenoh_macros::unstable] + // tags{publisher.matching_listener.pipe} pub fn with(self, handler: Handler) -> MatchingListenerBuilder<'a, Handler> where Handler: crate::prelude::IntoCallbackReceiverPair<'static, MatchingStatus>, @@ -1173,6 +1214,7 @@ pub(crate) struct MatchingListenerInner<'a> { #[zenoh_macros::unstable] impl<'a> MatchingListenerInner<'a> { #[inline] + // tags{publisher.matching_listener.undeclare} pub fn undeclare(self) -> MatchingListenerUndeclaration<'a> { Undeclarable::undeclare_inner(self, ()) } @@ -1206,6 +1248,7 @@ impl<'a> Undeclarable<(), MatchingListenerUndeclaration<'a>> for MatchingListene /// # }) /// ``` #[zenoh_macros::unstable] +// tags{publisher.matching_listener} pub struct MatchingListener<'a, Receiver> { pub(crate) listener: MatchingListenerInner<'a>, pub receiver: Receiver, @@ -1230,6 +1273,7 @@ impl<'a, Receiver> MatchingListener<'a, Receiver> { /// # }) /// ``` #[inline] + // tags{publisher.matching_listener.undeclare} pub fn undeclare(self) -> MatchingListenerUndeclaration<'a> { self.listener.undeclare() } @@ -1258,6 +1302,7 @@ impl std::ops::DerefMut for MatchingListener<'_, Receiver> { } #[zenoh_macros::unstable] +// tags{} pub struct MatchingListenerUndeclaration<'a> { subscriber: MatchingListenerInner<'a>, } diff --git a/zenoh/src/query.rs b/zenoh/src/query.rs index c4f3fb35e9..7f546e7048 100644 --- a/zenoh/src/query.rs +++ b/zenoh/src/query.rs @@ -33,6 +33,7 @@ pub use zenoh_protocol::core::ConsolidationMode; /// The operation: either manual or automatic. #[derive(Clone, Copy, Debug, PartialEq, Eq)] +// tags{} pub enum Mode { Auto, Manual(T), @@ -40,12 +41,14 @@ pub enum Mode { /// The replies consolidation strategy to apply on replies to a [`get`](Session::get). #[derive(Clone, Copy, Debug, PartialEq, Eq)] +// tags{query.options.consolidation} pub struct QueryConsolidation { pub(crate) mode: Mode, } impl QueryConsolidation { /// Automatic query consolidation strategy selection. + // tags{query.options.consolidation.auto} pub const AUTO: Self = Self { mode: Mode::Auto }; pub(crate) const fn from_mode(mode: ConsolidationMode) -> Self { @@ -55,6 +58,7 @@ impl QueryConsolidation { } /// Returns the requested [`ConsolidationMode`]. + // tags{} pub fn mode(&self) -> Mode { self.mode } @@ -79,10 +83,13 @@ impl Default for QueryConsolidation { /// Structs returned by a [`get`](Session::get). #[non_exhaustive] #[derive(Clone, Debug)] +// tags{query.reply} pub struct Reply { /// The result of this Reply. + // tags{query.reply.sample} pub sample: Result, /// The id of the zenoh instance that answered this Reply. + // tags{query.reply.replier_id} pub replier_id: ZenohId, } @@ -118,6 +125,7 @@ pub(crate) struct QueryState { /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] +// tags{} pub struct GetBuilder<'a, 'b, Handler> { pub(crate) session: &'a Session, pub(crate) selector: ZResult>, @@ -150,6 +158,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{query.callback} pub fn callback(self, callback: Callback) -> GetBuilder<'a, 'b, Callback> where Callback: Fn(Reply) + Send + Sync + 'static, @@ -203,6 +212,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{query.callback} pub fn callback_mut( self, callback: CallbackMut, @@ -233,6 +243,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{query.pipe} pub fn with(self, handler: Handler) -> GetBuilder<'a, 'b, Handler> where Handler: IntoCallbackReceiverPair<'static, Reply>, @@ -268,6 +279,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Change the target of the query. #[inline] + // tags{query.target.set} pub fn target(mut self, target: QueryTarget) -> Self { self.target = target; self @@ -275,6 +287,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Change the consolidation mode of the query. #[inline] + // tags{query.options.consolidation.set} pub fn consolidation>(mut self, consolidation: QC) -> Self { self.consolidation = consolidation.into(); self @@ -284,6 +297,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// to the ones that have the given [`Locality`](crate::prelude::Locality). #[zenoh_macros::unstable] #[inline] + // tags{query.allowed_destination.set} pub fn allowed_destination(mut self, destination: Locality) -> Self { self.destination = destination; self @@ -291,6 +305,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Set query timeout. #[inline] + // tags{query.timeout.set} pub fn timeout(mut self, timeout: Duration) -> Self { self.timeout = timeout; self @@ -298,6 +313,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Set query value. #[inline] + // tags{query.value.set} pub fn with_value(mut self, value: IntoValue) -> Self where IntoValue: Into, @@ -307,6 +323,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } #[zenoh_macros::unstable] + // tags{query.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self @@ -318,6 +335,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// If allowed to through `accept_replies(ReplyKeyExpr::Any)`, queryables may also reply on key /// expressions that don't intersect with the query's. #[zenoh_macros::unstable] + // tags{query.accept_replies.set} pub fn accept_replies(self, accept: ReplyKeyExpr) -> Self { let Self { session, @@ -348,10 +366,12 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { pub(crate) const _REPLY_KEY_EXPR_ANY_SEL_PARAM: &str = "_anyke"; #[zenoh_macros::unstable] +// tags{query.options.reply_key_expr_any_sel_param} pub const REPLY_KEY_EXPR_ANY_SEL_PARAM: &str = _REPLY_KEY_EXPR_ANY_SEL_PARAM; #[zenoh_macros::unstable] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +// tags{query.options.reply_key_expr} pub enum ReplyKeyExpr { Any, MatchingQuery, diff --git a/zenoh/src/queryable.rs b/zenoh/src/queryable.rs index 9ee73d1641..e36098a79b 100644 --- a/zenoh/src/queryable.rs +++ b/zenoh/src/queryable.rs @@ -64,6 +64,7 @@ impl Drop for QueryInner { /// Structs received by a [`Queryable`]. #[derive(Clone)] +// tags{queryable.query} pub struct Query { pub(crate) inner: Arc, } @@ -71,6 +72,7 @@ pub struct Query { impl Query { /// The full [`Selector`] of this Query. #[inline(always)] + // tags{queryable.query.selector.get} pub fn selector(&self) -> Selector<'_> { Selector { key_expr: self.inner.key_expr.clone(), @@ -80,23 +82,27 @@ impl Query { /// The key selector part of this Query. #[inline(always)] + // tags{queryable.query.key_expr.get} pub fn key_expr(&self) -> &KeyExpr<'static> { &self.inner.key_expr } /// This Query's selector parameters. #[inline(always)] + // tags{queryable.query.parameters.get} pub fn parameters(&self) -> &str { &self.inner.parameters } /// This Query's value. #[inline(always)] + // tags{queryable.query.value.get} pub fn value(&self) -> Option<&Value> { self.inner.value.as_ref() } #[zenoh_macros::unstable] + // tags{queryable.query.attachment.get} pub fn attachment(&self) -> Option<&Attachment> { self.inner.attachment.as_ref() } @@ -107,6 +113,7 @@ impl Query { /// Unless the query has enabled disjoint replies (you can check this through [`Query::accepts_replies`]), /// replying on a disjoint key expression will result in an error when resolving the reply. #[inline(always)] + // tags{queryable.query.reply} pub fn reply(&self, result: Result) -> ReplyBuilder<'_> { ReplyBuilder { query: self, @@ -117,6 +124,7 @@ impl Query { /// Queries may or may not accept replies on key expressions that do not intersect with their own key expression. /// This getter allows you to check whether or not a specific query does. #[zenoh_macros::unstable] + // tags{queryable.query.accepts_replies.get} pub fn accepts_replies(&self) -> ZResult { self._accepts_any_replies().map(|any| { if any { @@ -156,6 +164,7 @@ impl fmt::Display for Query { /// A builder returned by [`Query::reply()`](Query::reply). #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] +// tags{queryable.query.reply} pub struct ReplyBuilder<'a> { query: &'a Query, result: Result, @@ -164,6 +173,7 @@ pub struct ReplyBuilder<'a> { impl<'a> ReplyBuilder<'a> { #[allow(clippy::result_large_err)] #[zenoh_macros::unstable] + // tags{queryable.query.reply.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Result { match &mut self.result { Ok(sample) => { @@ -364,6 +374,7 @@ impl<'a> Undeclarable<(), QueryableUndeclaration<'a>> for CallbackQueryable<'a> /// # }) /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] +// tags{} pub struct QueryableUndeclaration<'a> { queryable: CallbackQueryable<'a>, } @@ -411,6 +422,7 @@ impl Drop for CallbackQueryable<'_> { /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] +// tags{} pub struct QueryableBuilder<'a, 'b, Handler> { pub(crate) session: SessionRef<'a>, pub(crate) key_expr: ZResult>, @@ -437,6 +449,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{queryable.callback} pub fn callback(self, callback: Callback) -> QueryableBuilder<'a, 'b, Callback> where Callback: Fn(Query) + Send + Sync + 'static, @@ -478,6 +491,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{queryable.callback} pub fn callback_mut( self, callback: CallbackMut, @@ -508,6 +522,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{queryable.pipe} pub fn with(self, handler: Handler) -> QueryableBuilder<'a, 'b, Handler> where Handler: crate::prelude::IntoCallbackReceiverPair<'static, Query>, @@ -532,6 +547,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// to the ones that have the given [`Locality`](crate::prelude::Locality). #[inline] #[zenoh_macros::unstable] + // tags{queryable.allowed_origin.set} pub fn allowed_origin(mut self, origin: Locality) -> Self { self.origin = origin; self @@ -540,6 +556,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { impl<'a, 'b, Handler> QueryableBuilder<'a, 'b, Handler> { /// Change queryable completeness. #[inline] + // tags{queryable.complete.set} pub fn complete(mut self, complete: bool) -> Self { self.complete = complete; self @@ -578,6 +595,7 @@ impl<'a, 'b, Handler> QueryableBuilder<'a, 'b, Handler> { /// ``` #[non_exhaustive] #[derive(Debug)] +// tags{queryable} pub struct Queryable<'a, Receiver> { pub(crate) queryable: CallbackQueryable<'a>, pub receiver: Receiver, @@ -585,6 +603,7 @@ pub struct Queryable<'a, Receiver> { impl<'a, Receiver> Queryable<'a, Receiver> { #[inline] + // tags{queryable.undeclare} pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self, ()) } diff --git a/zenoh/src/sample.rs b/zenoh/src/sample.rs index 5d707e5936..a5ee789d6d 100644 --- a/zenoh/src/sample.rs +++ b/zenoh/src/sample.rs @@ -28,6 +28,7 @@ pub type SourceSn = u64; /// The locality of samples to be received by subscribers or targeted by publishers. #[zenoh_macros::unstable] #[derive(Clone, Copy, Debug, Default, Serialize, PartialEq, Eq)] +// tags{sample.options.locality} pub enum Locality { SessionLocal, Remote, @@ -44,21 +45,30 @@ pub(crate) enum Locality { } #[derive(Debug, Clone, PartialEq, Eq, Default)] +// tags{sample.options.data_info} pub(crate) struct DataInfo { + // tags{sample.options.data_info.kind} pub kind: SampleKind, + // tags{sample.options.data_info.encoding} pub encoding: Option, + // tags{sample.options.data_info.timestamp} pub timestamp: Option, + // tags{sample.options.data_info.source_id} pub source_id: Option, + // tags{sample.options.data_info.source_sn} pub source_sn: Option, } /// Informations on the source of a zenoh [`Sample`]. #[zenoh_macros::unstable] #[derive(Debug, Clone)] +// tags{sample.options.source_info} pub struct SourceInfo { /// The [`ZenohId`] of the zenoh instance that published the concerned [`Sample`]. + // tags{sample.options.source_info.source_id} pub source_id: Option, /// The sequence number of the [`Sample`] from the source. + // tags{sample.options.source_info.source_sn} pub source_sn: Option, } @@ -124,6 +134,7 @@ mod attachment { } #[zenoh_macros::unstable] impl AttachmentBuilder { + // tags{sample.attachment.create} pub fn new() -> Self { Self { inner: Vec::new() } } @@ -136,6 +147,7 @@ mod attachment { /// Inserts a key-value pair to the attachment. /// /// Note that [`Attachment`] is a list of non-unique key-value pairs: inserting at the same key multiple times leads to both values being transmitted for that key. + // tags{sample.attachment.insert} pub fn insert + ?Sized, Value: AsRef<[u8]> + ?Sized>( &mut self, key: &Key, @@ -143,6 +155,7 @@ mod attachment { ) { self._insert(key.as_ref(), value.as_ref()) } + // tags{} pub fn build(self) -> Attachment { Attachment { inner: self.inner.into(), @@ -159,6 +172,7 @@ mod attachment { } #[zenoh_macros::unstable] #[derive(Clone)] + // tags{sample.attachment} pub struct Attachment { pub(crate) inner: ZBuf, } @@ -182,17 +196,21 @@ mod attachment { } #[zenoh_macros::unstable] impl Attachment { + // tags{sample.attachment.create} pub fn new() -> Self { Self { inner: ZBuf::empty(), } } + // tags{sample.attachment.create} pub fn is_empty(&self) -> bool { self.len() == 0 } + // tags{sample.attachment.len} pub fn len(&self) -> usize { self.iter().count() } + // tags{sample.attachment.get} pub fn iter(&self) -> AttachmentIterator { self.into_iter() } @@ -200,6 +218,7 @@ mod attachment { self.iter() .find_map(|(k, v)| (k.as_slice() == key).then_some(v)) } + // tags{sample.attachment.get} pub fn get>(&self, key: &Key) -> Option { self._get(key.as_ref()) } @@ -214,6 +233,7 @@ mod attachment { /// Note that [`Attachment`] is a list of non-unique key-value pairs: inserting at the same key multiple times leads to both values being transmitted for that key. /// /// [`Attachment`] is not very efficient at inserting, so if you wish to perform multiple inserts, it's generally better to [`Attachment::extend`] after performing the inserts on an [`AttachmentBuilder`] + // tags{sample.attachment.insert} pub fn insert + ?Sized, Value: AsRef<[u8]> + ?Sized>( &mut self, key: &Key, @@ -227,12 +247,14 @@ mod attachment { } self } + // tags{sample.attachment.extend} pub fn extend(&mut self, with: impl Into) -> &mut Self { let with = with.into(); self._extend(with) } } #[zenoh_macros::unstable] + // tags{} pub struct AttachmentIterator<'a> { reader: ZBufReader<'a>, } @@ -317,14 +339,19 @@ pub use attachment::{Attachment, AttachmentBuilder, AttachmentIterator}; /// A zenoh sample. #[non_exhaustive] #[derive(Clone, Debug)] +// tags{sample} pub struct Sample { /// The key expression on which this Sample was published. + // tags{sample.key_expr} pub key_expr: KeyExpr<'static>, /// The value of this Sample. + // tags{sample.value} pub value: Value, /// The kind of this Sample. + // tags{sample.kind} pub kind: SampleKind, /// The [`Timestamp`] of this Sample. + // tags{sample.timestamp} pub timestamp: Option, #[cfg(feature = "unstable")] @@ -335,6 +362,7 @@ pub struct Sample { /// /// /// Infos on the source of this Sample. + // tags{sample.source_info} pub source_info: SourceInfo, #[cfg(feature = "unstable")] @@ -345,12 +373,14 @@ pub struct Sample { /// /// /// A map of key-value pairs, where each key and value are byte-slices. + // tags{sample.attachment} pub attachment: Option, } impl Sample { /// Creates a new Sample. #[inline] + // tags{sample.create} pub fn new(key_expr: IntoKeyExpr, value: IntoValue) -> Self where IntoKeyExpr: Into>, @@ -369,6 +399,7 @@ impl Sample { } /// Creates a new Sample. #[inline] + // tags{sample.create.from_value} pub fn try_from( key_expr: TryIntoKeyExpr, value: IntoValue, @@ -392,6 +423,7 @@ impl Sample { /// Creates a new Sample with optional data info. #[inline] + // tags{sample.create.from_value_and_datainfo} pub(crate) fn with_info( key_expr: KeyExpr<'static>, payload: ZBuf, @@ -428,12 +460,14 @@ impl Sample { /// Gets the timestamp of this Sample. #[inline] + // tags{sample.timestamp.get} pub fn get_timestamp(&self) -> Option<&Timestamp> { self.timestamp.as_ref() } /// Sets the timestamp of this Sample. #[inline] + // tags{sample.timestamp.set} pub fn with_timestamp(mut self, timestamp: Timestamp) -> Self { self.timestamp = Some(timestamp); self @@ -442,6 +476,7 @@ impl Sample { /// Sets the source info of this Sample. #[zenoh_macros::unstable] #[inline] + // tags{sample.source_info.set} pub fn with_source_info(mut self, source_info: SourceInfo) -> Self { self.source_info = source_info; self @@ -451,6 +486,7 @@ impl Sample { /// Ensure that an associated Timestamp is present in this Sample. /// If not, a new one is created with the current system time and 0x00 as id. /// Get the timestamp of this sample (either existing one or newly created) + // tags{sample.timestamp.ensure} pub fn ensure_timestamp(&mut self) -> &Timestamp { if let Some(ref timestamp) = self.timestamp { timestamp @@ -462,17 +498,20 @@ impl Sample { } #[zenoh_macros::unstable] + // tags{sample.attachment.get} pub fn attachment(&self) -> Option<&Attachment> { self.attachment.as_ref() } #[zenoh_macros::unstable] + // tags{sample.attachment.get} pub fn attachment_mut(&mut self) -> &mut Option { &mut self.attachment } #[allow(clippy::result_large_err)] #[zenoh_macros::unstable] + // tags{sample.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self diff --git a/zenoh/src/scouting.rs b/zenoh/src/scouting.rs index ea09823ea1..1a0d7ea50a 100644 --- a/zenoh/src/scouting.rs +++ b/zenoh/src/scouting.rs @@ -46,6 +46,7 @@ pub use zenoh_protocol::scouting::Hello; /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] +// tags{scout} pub struct ScoutBuilder { pub(crate) what: WhatAmIMatcher, pub(crate) config: ZResult, @@ -69,6 +70,7 @@ impl ScoutBuilder { /// # }) /// ``` #[inline] + // tags{scout.callback} pub fn callback(self, callback: Callback) -> ScoutBuilder where Callback: Fn(Hello) + Send + Sync + 'static, @@ -105,6 +107,7 @@ impl ScoutBuilder { /// # }) /// ``` #[inline] + // tags{scout.callback} pub fn callback_mut( self, callback: CallbackMut, @@ -134,6 +137,7 @@ impl ScoutBuilder { /// # }) /// ``` #[inline] + // tags{scout.pipe} pub fn with(self, handler: Handler) -> ScoutBuilder where Handler: crate::prelude::IntoCallbackReceiverPair<'static, Hello>, @@ -219,6 +223,7 @@ impl ScoutInner { /// scout.stop(); /// # }) /// ``` + // tags{scout.stop} pub fn stop(self) { // This drops the inner `stop_sender` and hence stops the scouting receiver std::mem::drop(self); @@ -251,6 +256,7 @@ impl fmt::Debug for ScoutInner { /// ``` #[non_exhaustive] #[derive(Debug)] +// tags{scout} pub struct Scout { pub(crate) scout: ScoutInner, pub receiver: Receiver, @@ -282,6 +288,7 @@ impl Scout { /// scout.stop(); /// # }) /// ``` + // tags{scout.stop} pub fn stop(self) { self.scout.stop() } diff --git a/zenoh/src/selector.rs b/zenoh/src/selector.rs index 2a9a38c02c..c1264084da 100644 --- a/zenoh/src/selector.rs +++ b/zenoh/src/selector.rs @@ -63,6 +63,7 @@ use std::{ /// whose key expression match query's key expression are accepted. `_anyke` disables the query-reply key expression matching check. #[non_exhaustive] #[derive(Clone, PartialEq, Eq)] +// tags{selector} pub struct Selector<'a> { /// The part of this selector identifying which keys should be part of the selection. pub key_expr: KeyExpr<'a>, @@ -70,13 +71,16 @@ pub struct Selector<'a> { pub(crate) parameters: Cow<'a, str>, } +// tags{selector.options.time_range_key} pub const TIME_RANGE_KEY: &str = "_time"; impl<'a> Selector<'a> { /// Gets the parameters as a raw string. + // tags{selector.parameters.get} pub fn parameters(&self) -> &str { &self.parameters } /// Extracts the selector parameters into a hashmap, returning an error in case of duplicated parameter names. + // tags{selector.parameters.get} pub fn parameters_map(&'a self) -> ZResult> where K: AsRef + std::hash::Hash + std::cmp::Eq, @@ -86,10 +90,12 @@ impl<'a> Selector<'a> { self.decode_into_map() } /// Extracts the selector parameters' name-value pairs into a hashmap, returning an error in case of duplicated parameters. + // tags{selector.parameters.get} pub fn parameters_cowmap(&'a self) -> ZResult, Cow<'a, str>>> { self.decode_into_map() } /// Extracts the selector parameters' name-value pairs into a hashmap, returning an error in case of duplicated parameters. + // tags{selector.parameters.get} pub fn parameters_stringmap(&'a self) -> ZResult> { self.decode_into_map() } @@ -97,6 +103,7 @@ impl<'a> Selector<'a> { /// /// Note that calling this function may cause an allocation and copy if the selector's parameters wasn't /// already owned by `self`. `self` owns its parameters as soon as this function returns. + // tags{selector.parameters.get} pub fn parameters_mut(&mut self) -> &mut String { if let Cow::Borrowed(s) = self.parameters { self.parameters = Cow::Owned(s.to_owned()) @@ -107,15 +114,18 @@ impl<'a> Selector<'a> { unsafe { std::hint::unreachable_unchecked() } // this is safe because we just replaced the borrowed variant } } + // tags{selector.parameters.get} pub fn set_parameters(&mut self, selector: impl Into>) { self.parameters = selector.into(); } + // tags{} pub fn borrowing_clone(&'a self) -> Self { Selector { key_expr: self.key_expr.clone(), parameters: self.parameters.as_ref().into(), } } + // tags{} pub fn into_owned(self) -> Selector<'static> { Selector { key_expr: self.key_expr.into_owned(), @@ -124,22 +134,26 @@ impl<'a> Selector<'a> { } #[deprecated = "If you have ownership of this selector, prefer `Selector::into_owned`"] + // tags{} pub fn to_owned(&self) -> Selector<'static> { self.borrowing_clone().into_owned() } /// Returns this selectors components as a tuple. + /// tags{} pub fn split(self) -> (KeyExpr<'a>, Cow<'a, str>) { (self.key_expr, self.parameters) } /// Sets the `parameters` part of this `Selector`. + // tags{selector.parameters.set} #[inline(always)] pub fn with_parameters(mut self, parameters: &'a str) -> Self { self.parameters = parameters.into(); self } + // tags{selector.parameters.set} pub fn extend<'b, I, K, V>(&'b mut self, parameters: I) where I: IntoIterator, @@ -154,6 +168,7 @@ impl<'a> Selector<'a> { } /// Sets the time range targeted by the selector. + // tags{selector.parameters.time_range.set} pub fn with_time_range(&mut self, time_range: TimeRange) { self.remove_time_range(); let selector = self.parameters_mut(); @@ -164,6 +179,7 @@ impl<'a> Selector<'a> { write!(selector, "{TIME_RANGE_KEY}={time_range}").unwrap(); // This unwrap is safe because `String: Write` should be infallibe. } + // tags{selector.parameters.time_range.remove} pub fn remove_time_range(&mut self) { let selector = self.parameters_mut(); @@ -186,6 +202,7 @@ impl<'a> Selector<'a> { } } #[cfg(any(feature = "unstable", test))] + // tags{} pub(crate) fn parameter_index(&self, param_name: &str) -> ZResult> { let starts_with_param = |s: &str| { if let Some(rest) = s.strip_prefix(param_name) { @@ -321,6 +338,7 @@ type ExtractedValue<'a, VS: Parameters<'a>> = <::Item a /// A trait to help decode zenoh selector parameters. /// /// Most methods will return an Error if duplicates of a same parameter are found, to avoid HTTP Parameter Pollution like vulnerabilities. +// tags{selector.parameters} pub trait Parameters<'a> { type Decoder: Iterator + 'a; /// Returns this selector's parameters as an iterator. @@ -329,6 +347,7 @@ pub trait Parameters<'a> { ::Item: Parameter; /// Extracts all parameters into a HashMap, returning an error if duplicate parameters arrise. + // tags{selector.parameters.get} fn decode_into_map(&'a self) -> ZResult> where ::Item: Parameter, @@ -353,6 +372,7 @@ pub trait Parameters<'a> { /// Extracts the requested parameters from the selector parameters. /// /// The default implementation is done in a single pass through the selector parameters, returning an error if any of the requested parameters are present more than once. + // tags{selector.parameters.get} fn get_parameters( &'a self, names: [&str; N], @@ -383,6 +403,7 @@ pub trait Parameters<'a> { /// Extracts the requested arguments from the selector parameters as booleans, following the Zenoh convention that if a parameter name is present and has a value different from "false", its value is truthy. /// /// The default implementation is done in a single pass through the selector parameters, returning an error if some of the requested parameters are present more than once. + // tags{selector.parameters.get.booleans} fn get_bools(&'a self, names: [&str; N]) -> ZResult<[bool; N]> where ::Item: Parameter, @@ -396,6 +417,7 @@ pub trait Parameters<'a> { /// Extracts the standardized `_time` argument from the selector parameters. /// /// The default implementation still causes a complete pass through the selector parameters to ensure that there are no duplicates of the `_time` key. + // tags{selector.parameters.time_range.get} fn time_range(&'a self) -> ZResult> where ::Item: Parameter, diff --git a/zenoh/src/session.rs b/zenoh/src/session.rs index d52c446d3d..20d92b5e30 100644 --- a/zenoh/src/session.rs +++ b/zenoh/src/session.rs @@ -279,6 +279,7 @@ impl Resource { } #[derive(Clone)] +// tags{} pub enum SessionRef<'a> { Borrow(&'a Session), Shared(Arc), @@ -368,6 +369,7 @@ impl fmt::Debug for SessionRef<'_> { } /// A trait implemented by types that can be undeclared. +// tags{} pub trait Undeclarable> where O: Resolve + Send, @@ -387,6 +389,7 @@ where /// A zenoh session. /// +// tags{session} pub struct Session { pub(crate) runtime: Runtime, pub(crate) state: Arc>, @@ -453,6 +456,7 @@ impl Session { /// }).await; /// # }) /// ``` + // tags{} pub fn into_arc(self) -> Arc { Arc::new(self) } @@ -484,16 +488,19 @@ impl Session { /// }).await; /// # }) /// ``` + // tags{} pub fn leak(s: Self) -> &'static mut Self { Box::leak(Box::new(s)) } /// Returns the identifier of the current session. `zid()` is a convenient shortcut. /// See [`Session::info()`](`Session::info()`) and [`SessionInfo::zid()`](`SessionInfo::zid()`) for more details. + // tags{session.zid.get} pub fn zid(&self) -> ZenohId { self.info().zid().res_sync() } + // tags{session.hlc.get} pub fn hlc(&self) -> Option<&HLC> { self.runtime.hlc() } @@ -512,6 +519,7 @@ impl Session { /// session.close().res().await.unwrap(); /// # }) /// ``` + // tags{session.close} pub fn close(self) -> impl Resolve> { ResolveFuture::new(async move { trace!("close()"); @@ -524,6 +532,7 @@ impl Session { }) } + // tags{session.undeclare} pub fn undeclare<'a, T, O>(&'a self, decl: T) -> O where O: Resolve>, @@ -559,6 +568,8 @@ impl Session { /// let _ = session.config().insert_json5("connect/endpoints", r#"["tcp/127.0.0.1/7447"]"#); /// # }) /// ``` + // tags{session.config.get} + // tags{session.config.notifier.get} pub fn config(&self) -> &Notifier { self.runtime.config() } @@ -619,6 +630,7 @@ impl Session { /// let key_expr = session.declare_keyexpr("key/expression").res().await.unwrap(); /// # }) /// ``` + // tags{session.declare_keyexpr} pub fn declare_keyexpr<'a, 'b: 'a, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -686,6 +698,7 @@ impl Session { /// # }) /// ``` #[inline] + // tags{session.put} pub fn put<'a, 'b: 'a, TryIntoKeyExpr, IntoValue>( &'a self, key_expr: TryIntoKeyExpr, @@ -721,6 +734,7 @@ impl Session { /// # }) /// ``` #[inline] + // tags{session.delete} pub fn delete<'a, 'b: 'a, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -758,6 +772,7 @@ impl Session { /// } /// # }) /// ``` + // tags{session.query} pub fn get<'a, 'b: 'a, IntoSelector>( &'a self, selector: IntoSelector, @@ -2519,6 +2534,7 @@ impl fmt::Debug for Session { /// }).await; /// # }) /// ``` +// tags{} pub trait SessionDeclarations<'s, 'a> { /// Create a [`Subscriber`](crate::subscriber::Subscriber) for the given key expression. /// @@ -2543,6 +2559,7 @@ pub trait SessionDeclarations<'s, 'a> { /// }).await; /// # }) /// ``` + // tags{session.declare_subscriber} fn declare_subscriber<'b, TryIntoKeyExpr>( &'s self, key_expr: TryIntoKeyExpr, @@ -2578,6 +2595,7 @@ pub trait SessionDeclarations<'s, 'a> { /// }).await; /// # }) /// ``` + // tags{session.declare_queryable} fn declare_queryable<'b, TryIntoKeyExpr>( &'s self, key_expr: TryIntoKeyExpr, @@ -2605,6 +2623,7 @@ pub trait SessionDeclarations<'s, 'a> { /// publisher.put("value").res().await.unwrap(); /// # }) /// ``` + // tags{session.declare_publisher} fn declare_publisher<'b, TryIntoKeyExpr>( &'s self, key_expr: TryIntoKeyExpr, @@ -2629,6 +2648,7 @@ pub trait SessionDeclarations<'s, 'a> { /// .unwrap(); /// # }) /// ``` + // tags{session.liveliness} #[zenoh_macros::unstable] fn liveliness(&'s self) -> Liveliness<'a>; /// Get informations about the zenoh [`Session`](Session). diff --git a/zenoh/src/subscriber.rs b/zenoh/src/subscriber.rs index 7258833d28..81c7bf45ed 100644 --- a/zenoh/src/subscriber.rs +++ b/zenoh/src/subscriber.rs @@ -131,6 +131,7 @@ impl<'a> PullSubscriberInner<'a> { /// # }) /// ``` #[inline] + // tags{subscriber.pull} pub fn pull(&self) -> impl Resolve> + '_ { self.inner.session.pull(&self.inner.state.key_expr) } @@ -158,6 +159,7 @@ impl<'a> PullSubscriberInner<'a> { /// # }) /// ``` #[inline] + // tags{subscriber.undeclare} pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self.inner, ()) } @@ -186,6 +188,7 @@ impl<'a> SubscriberInner<'a> { /// # }) /// ``` #[inline] + // tags{subscriber.undeclare} pub fn undeclare(self) -> SubscriberUndeclaration<'a> { Undeclarable::undeclare_inner(self, ()) } @@ -214,6 +217,7 @@ impl<'a> Undeclarable<(), SubscriberUndeclaration<'a>> for SubscriberInner<'a> { /// # }) /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] +// tags{} pub struct SubscriberUndeclaration<'a> { subscriber: SubscriberInner<'a>, } @@ -250,6 +254,7 @@ impl Drop for SubscriberInner<'_> { /// The mode for pull subscribers. #[non_exhaustive] #[derive(Debug, Clone, Copy)] +// tags{subscriber.option.pull_mode} pub struct PullMode; impl From for SubMode { @@ -267,6 +272,7 @@ impl From for Mode { /// The mode for push subscribers. #[non_exhaustive] #[derive(Debug, Clone, Copy)] +// tags{push_subscriber.option.push_mode} pub struct PushMode; impl From for SubMode { @@ -300,6 +306,7 @@ impl From for Mode { /// ``` #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] +// tags{} pub struct SubscriberBuilder<'a, 'b, Mode, Handler> { #[cfg(feature = "unstable")] pub session: SessionRef<'a>, @@ -350,6 +357,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{subscriber.callback} pub fn callback(self, callback: Callback) -> SubscriberBuilder<'a, 'b, Mode, Callback> where Callback: Fn(Sample) + Send + Sync + 'static, @@ -393,6 +401,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{subscriber.callback} pub fn callback_mut( self, callback: CallbackMut, @@ -423,6 +432,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// # }) /// ``` #[inline] + // tags{subscriber.pipe} pub fn with(self, handler: Handler) -> SubscriberBuilder<'a, 'b, Mode, Handler> where Handler: crate::prelude::IntoCallbackReceiverPair<'static, Sample>, @@ -448,6 +458,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Change the subscription reliability. #[inline] + // tags{subscriber.reliability.set} pub fn reliability(mut self, reliability: Reliability) -> Self { self.reliability = reliability; self @@ -455,6 +466,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Change the subscription reliability to `Reliable`. #[inline] + // tags{subscriber.reliability.set.reliable} pub fn reliable(mut self) -> Self { self.reliability = Reliability::Reliable; self @@ -462,6 +474,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Change the subscription reliability to `BestEffort`. #[inline] + // tags{subscriber.reliability.set.best_effort} pub fn best_effort(mut self) -> Self { self.reliability = Reliability::BestEffort; self @@ -471,6 +484,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// to the ones that have the given [`Locality`](crate::prelude::Locality). #[zenoh_macros::unstable] #[inline] + // tags{subscriber.allowed_origin.set} pub fn allowed_origin(mut self, origin: Locality) -> Self { self.origin = origin; self @@ -478,6 +492,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Change the subscription mode to Pull. #[inline] + // tags{subscriber.pull_mode.set} pub fn pull_mode(self) -> SubscriberBuilder<'a, 'b, PullMode, Handler> { let SubscriberBuilder { session, @@ -499,6 +514,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Change the subscription mode to Push. #[inline] + // tags{subscriber.push_mode.set} pub fn push_mode(self) -> SubscriberBuilder<'a, 'b, PushMode, Handler> { let SubscriberBuilder { session, @@ -653,6 +669,7 @@ where /// ``` #[non_exhaustive] #[derive(Debug)] +// tags{subscriber} pub struct Subscriber<'a, Receiver> { pub(crate) subscriber: SubscriberInner<'a>, pub receiver: Receiver, @@ -687,6 +704,7 @@ pub struct Subscriber<'a, Receiver> { /// # }) /// ``` #[non_exhaustive] +// tags{subscriber} pub struct PullSubscriber<'a, Receiver> { pub(crate) subscriber: PullSubscriberInner<'a>, pub receiver: Receiver, @@ -726,6 +744,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { /// # }) /// ``` #[inline] + // tags{subscriber.pull} pub fn pull(&self) -> impl Resolve> + '_ { self.subscriber.pull() } @@ -750,6 +769,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { /// # }) /// ``` #[inline] + // tags{subscriber.undeclare} pub fn undeclare(self) -> impl Resolve> + 'a { self.subscriber.undeclare() } @@ -757,6 +777,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { impl<'a, Receiver> Subscriber<'a, Receiver> { /// Returns the [`KeyExpr`] this Subscriber subscribes to. + // tags{subscriber.key_expr.get} pub fn key_expr(&self) -> &KeyExpr<'static> { &self.subscriber.state.key_expr } @@ -780,6 +801,7 @@ impl<'a, Receiver> Subscriber<'a, Receiver> { /// # }) /// ``` #[inline] + // tags{subscriber.undeclare} pub fn undeclare(self) -> SubscriberUndeclaration<'a> { self.subscriber.undeclare() } diff --git a/zenoh/src/value.rs b/zenoh/src/value.rs index 849cfd57d5..fc412f2f3a 100644 --- a/zenoh/src/value.rs +++ b/zenoh/src/value.rs @@ -31,6 +31,7 @@ use zenoh_shm::SharedMemoryBuf; /// A zenoh Value. #[non_exhaustive] #[derive(Clone)] +// tags{value} pub struct Value { /// The payload of this Value. pub payload: ZBuf, @@ -40,6 +41,7 @@ pub struct Value { impl Value { /// Creates a new zenoh Value. + // tags{value.create} pub fn new(payload: ZBuf) -> Self { Value { payload, @@ -57,6 +59,7 @@ impl Value { /// Sets the encoding of this zenoh Value. #[inline(always)] + // tags{value.encoding.set} pub fn encoding(mut self, encoding: Encoding) -> Self { self.encoding = encoding; self