From b7dcc295b6325deaf36fa3a06b4bd0bd07e1c24b Mon Sep 17 00:00:00 2001 From: Pierre Avital Date: Mon, 29 Jan 2024 10:19:18 +0100 Subject: [PATCH 1/5] Start tagging features in Zenoh --- commons/zenoh-protocol/src/core/mod.rs | 2 ++ commons/zenoh-protocol/src/network/mod.rs | 2 ++ commons/zenoh-protocol/src/scouting/mod.rs | 2 ++ commons/zenoh-protocol/src/transport/mod.rs | 2 ++ commons/zenoh-protocol/src/zenoh/mod.rs | 2 ++ zenoh/src/info.rs | 7 +++++++ zenoh/src/net/routing/pubsub.rs | 2 +- zenoh/src/sample.rs | 1 + zenoh/src/session.rs | 16 ++++++++++++++++ zenoh/src/subscriber.rs | 11 +++++++++++ 10 files changed, 46 insertions(+), 1 deletion(-) diff --git a/commons/zenoh-protocol/src/core/mod.rs b/commons/zenoh-protocol/src/core/mod.rs index 2547034c44..bb76cea913 100644 --- a/commons/zenoh-protocol/src/core/mod.rs +++ b/commons/zenoh-protocol/src/core/mod.rs @@ -345,6 +345,8 @@ impl TryFrom for Priority { } } +/// The reliability request of a subscriber. +// tags{options.reliability} #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] pub enum Reliability { diff --git a/commons/zenoh-protocol/src/network/mod.rs b/commons/zenoh-protocol/src/network/mod.rs index 1be58db5cc..af7ee6d5f5 100644 --- a/commons/zenoh-protocol/src/network/mod.rs +++ b/commons/zenoh-protocol/src/network/mod.rs @@ -11,6 +11,8 @@ // Contributors: // ZettaScale Zenoh Team, // + +// ignore_tagging pub mod declare; pub mod oam; pub mod push; diff --git a/commons/zenoh-protocol/src/scouting/mod.rs b/commons/zenoh-protocol/src/scouting/mod.rs index 9e7fd27c2d..3f288e79b3 100644 --- a/commons/zenoh-protocol/src/scouting/mod.rs +++ b/commons/zenoh-protocol/src/scouting/mod.rs @@ -11,6 +11,8 @@ // Contributors: // ZettaScale Zenoh Team, // + +// ignore_tagging pub mod hello; pub mod scout; diff --git a/commons/zenoh-protocol/src/transport/mod.rs b/commons/zenoh-protocol/src/transport/mod.rs index cdf994e5dd..ef531459ca 100644 --- a/commons/zenoh-protocol/src/transport/mod.rs +++ b/commons/zenoh-protocol/src/transport/mod.rs @@ -11,6 +11,8 @@ // Contributors: // ZettaScale Zenoh Team, // + +// ignore_tagging pub mod close; pub mod fragment; pub mod frame; diff --git a/commons/zenoh-protocol/src/zenoh/mod.rs b/commons/zenoh-protocol/src/zenoh/mod.rs index e67576e673..6bb6bc96c6 100644 --- a/commons/zenoh-protocol/src/zenoh/mod.rs +++ b/commons/zenoh-protocol/src/zenoh/mod.rs @@ -11,6 +11,8 @@ // Contributors: // ZettaScale Zenoh Team, // + +// ignore_tagging pub mod ack; pub mod del; pub mod err; diff --git a/zenoh/src/info.rs b/zenoh/src/info.rs index 848a5cb68b..2220f2a214 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} 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.info.routers_zid} 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.info.peers_zid} pub fn peers_zid(&self) -> PeersZidBuilder<'_> { PeersZidBuilder { session: self.session.clone(), diff --git a/zenoh/src/net/routing/pubsub.rs b/zenoh/src/net/routing/pubsub.rs index e9dc80b024..c7a913bc29 100644 --- a/zenoh/src/net/routing/pubsub.rs +++ b/zenoh/src/net/routing/pubsub.rs @@ -303,7 +303,7 @@ fn register_peer_subscription( } } -pub fn declare_peer_subscription( +pub(crate) fn declare_peer_subscription( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, diff --git a/zenoh/src/sample.rs b/zenoh/src/sample.rs index 5d707e5936..46e73b01f0 100644 --- a/zenoh/src/sample.rs +++ b/zenoh/src/sample.rs @@ -26,6 +26,7 @@ use zenoh_protocol::core::Encoding; pub type SourceSn = u64; /// The locality of samples to be received by subscribers or targeted by publishers. +// tags{options.locality} #[zenoh_macros::unstable] #[derive(Clone, Copy, Debug, Default, Serialize, PartialEq, Eq)] pub enum Locality { diff --git a/zenoh/src/session.rs b/zenoh/src/session.rs index 7897b293f9..bdc928fd49 100644 --- a/zenoh/src/session.rs +++ b/zenoh/src/session.rs @@ -390,6 +390,7 @@ impl Session { /// }).await; /// # }) /// ``` + // tags{session.rc} pub fn into_arc(self) -> Arc { Arc::new(self) } @@ -421,16 +422,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} pub fn zid(&self) -> ZenohId { self.info().zid().res_sync() } + // tags{session.clock} pub fn hlc(&self) -> Option<&HLC> { self.runtime.hlc() } @@ -449,6 +453,7 @@ impl Session { /// session.close().res().await.unwrap(); /// # }) /// ``` + // tags{session.close} pub fn close(self) -> impl Resolve> { ResolveFuture::new(async move { trace!("close()"); @@ -461,6 +466,7 @@ impl Session { }) } + // tags{} pub fn undeclare<'a, T, O>(&'a self, decl: T) -> O where O: Resolve>, @@ -496,6 +502,7 @@ impl Session { /// let _ = session.config().insert_json5("connect/endpoints", r#"["tcp/127.0.0.1/7447"]"#); /// # }) /// ``` + // tags{session.config{get, subscribe}} pub fn config(&self) -> &Notifier { self.runtime.config() } @@ -511,6 +518,7 @@ impl Session { /// let info = session.info(); /// # }) /// ``` + // tags{session.info} pub fn info(&self) -> SessionInfo { SessionInfo { session: SessionRef::Borrow(self), @@ -535,6 +543,7 @@ impl Session { /// } /// # }) /// ``` + // tags{session.declare_subscriber} pub fn declare_subscriber<'a, 'b, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -575,6 +584,7 @@ impl Session { /// } /// # }) /// ``` + // tags{session.declare_queryable} pub fn declare_queryable<'a, 'b, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -611,6 +621,7 @@ impl Session { /// publisher.put("value").res().await.unwrap(); /// # }) /// ``` + // tags{session.declare_publisher} pub fn declare_publisher<'a, 'b, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -642,6 +653,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, @@ -708,6 +720,7 @@ impl Session { /// .unwrap(); /// # }) /// ``` + // tags{session.put} #[inline] pub fn put<'a, 'b: 'a, TryIntoKeyExpr, IntoValue>( &'a self, @@ -743,6 +756,7 @@ impl Session { /// session.delete("key/expression").res().await.unwrap(); /// # }) /// ``` + // tags{session.delete} #[inline] pub fn delete<'a, 'b: 'a, TryIntoKeyExpr>( &'a self, @@ -781,6 +795,7 @@ impl Session { /// } /// # }) /// ``` + // tags{session.get} pub fn get<'a, 'b: 'a, IntoSelector>( &'a self, selector: IntoSelector, @@ -825,6 +840,7 @@ impl Session { /// .unwrap(); /// # }) /// ``` + // tags{liveliness} #[zenoh_macros::unstable] pub fn liveliness(&self) -> Liveliness { Liveliness { diff --git a/zenoh/src/subscriber.rs b/zenoh/src/subscriber.rs index 7258833d28..3803ae5cf2 100644 --- a/zenoh/src/subscriber.rs +++ b/zenoh/src/subscriber.rs @@ -349,6 +349,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{session.declare_subscriber.cb} #[inline] pub fn callback(self, callback: Callback) -> SubscriberBuilder<'a, 'b, Mode, Callback> where @@ -392,6 +393,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{session.declare_subscriber.cb.locked} #[inline] pub fn callback_mut( self, @@ -422,6 +424,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// } /// # }) /// ``` + // tags{session.declare_subscriber.cb.generic} #[inline] pub fn with(self, handler: Handler) -> SubscriberBuilder<'a, 'b, Mode, Handler> where @@ -447,6 +450,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { } impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Change the subscription reliability. + // tags{session.declare_subscriber.options.reliability} #[inline] pub fn reliability(mut self, reliability: Reliability) -> Self { self.reliability = reliability; @@ -469,6 +473,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Restrict the matching publications that will be receive by this [`Subscriber`] /// to the ones that have the given [`Locality`](crate::prelude::Locality). + // tags{session.declare_subscriber.options.locality} #[zenoh_macros::unstable] #[inline] pub fn allowed_origin(mut self, origin: Locality) -> Self { @@ -477,6 +482,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { } /// Change the subscription mode to Pull. + // tags{session.declare_subscriber.options.pull} #[inline] pub fn pull_mode(self) -> SubscriberBuilder<'a, 'b, PullMode, Handler> { let SubscriberBuilder { @@ -498,6 +504,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { } /// Change the subscription mode to Push. + // tags{session.declare_subscriber.options.push} #[inline] pub fn push_mode(self) -> SubscriberBuilder<'a, 'b, PushMode, Handler> { let SubscriberBuilder { @@ -725,6 +732,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { /// subscriber.pull(); /// # }) /// ``` + // tags{session.declare_subscriber.pull} #[inline] pub fn pull(&self) -> impl Resolve> + '_ { self.subscriber.pull() @@ -749,6 +757,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { /// subscriber.undeclare().res().await.unwrap(); /// # }) /// ``` + // tags{session.declare_subscriber.pull.undeclare} #[inline] pub fn undeclare(self) -> impl Resolve> + 'a { self.subscriber.undeclare() @@ -757,6 +766,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { impl<'a, Receiver> Subscriber<'a, Receiver> { /// Returns the [`KeyExpr`] this Subscriber subscribes to. + // tags{session.declare_subscriber.push.key_expr} pub fn key_expr(&self) -> &KeyExpr<'static> { &self.subscriber.state.key_expr } @@ -779,6 +789,7 @@ impl<'a, Receiver> Subscriber<'a, Receiver> { /// subscriber.undeclare().res().await.unwrap(); /// # }) /// ``` + // tags{session.declare_subscriber.push.undeclare} #[inline] pub fn undeclare(self) -> SubscriberUndeclaration<'a> { self.subscriber.undeclare() From 5ac67953304edc47892c485441cd1fa7a7af9037 Mon Sep 17 00:00:00 2001 From: Michael Ilyin Date: Sun, 4 Feb 2024 23:15:29 +0100 Subject: [PATCH 2/5] more tags --- zenoh/src/handlers.rs | 5 +++++ zenoh/src/key_expr.rs | 17 ++++++++++++++++- zenoh/src/lib.rs | 10 ++++++++++ zenoh/src/liveliness.rs | 17 +++++++++++++++++ zenoh/src/net/codec/mod.rs | 2 ++ zenoh/src/net/routing/face.rs | 3 +++ zenoh/src/net/routing/router.rs | 1 + zenoh/src/net/tests/tables.rs | 2 +- zenoh/src/publication.rs | 1 + 9 files changed, 56 insertions(+), 2 deletions(-) diff --git a/zenoh/src/handlers.rs b/zenoh/src/handlers.rs index 69828a5d7f..59e9a007db 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 `()`. +// ignore_tagging pub trait IntoCallbackReceiverPair<'a, T> { type Receiver; fn into_cb_receiver_pair(self) -> (Callback<'a, T>, Self::Receiver); @@ -56,6 +57,8 @@ impl IntoCallbackReceiverPair<'static, T> ) } } + +// ignore_tagging pub struct DefaultHandler; impl IntoCallbackReceiverPair<'static, T> for DefaultHandler { type Receiver = flume::Receiver; @@ -82,6 +85,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). +// ignore_tagging pub fn locked(fnmut: impl FnMut(T)) -> impl Fn(T) { let lock = std::sync::Mutex::new(fnmut); move |x| zlock!(lock)(x) @@ -96,6 +100,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. +// ignore_tagging pub struct CallbackPair where DropFn: FnMut() + Send + Sync + 'static, diff --git a/zenoh/src/key_expr.rs b/zenoh/src/key_expr.rs index 9f6418974e..2c42024a5b 100644 --- a/zenoh/src/key_expr.rs +++ b/zenoh/src/key_expr.rs @@ -53,6 +53,8 @@ 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")] @@ -75,6 +77,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.from_unchecked} pub unsafe fn from_string_unchecked(s: String) -> Self { Self(KeyExprInner::Owned(OwnedKeyExpr::from_string_unchecked(s))) } @@ -83,6 +86,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.from_unchecked} pub unsafe fn from_boxed_string_unchecked(s: Box) -> Self { Self(KeyExprInner::Owned( OwnedKeyExpr::from_boxed_string_unchecked(s), @@ -96,6 +100,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.new} pub fn new(t: T) -> Result where Self: TryFrom, @@ -106,6 +111,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. + // ignore_tagging pub fn borrowing_clone(&'a self) -> Self { let inner = match &self.0 { KeyExprInner::Borrowed(key_expr) => KeyExprInner::Borrowed(key_expr), @@ -143,6 +149,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, @@ -156,16 +163,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. - pub unsafe fn from_str_uncheckend(s: &'a str) -> Self { + // tags{keyexpr.from_unchecked} + pub unsafe fn from_str_unchecked(s: &'a str) -> Self { keyexpr::from_str_unchecked(s).into() } /// Returns the borrowed version of `self` + // ignore_tagging pub fn as_keyexpr(&self) -> &keyexpr { self } /// Ensures `self` owns all of its data, and informs rustc that it does. + // ignore_tagging pub fn into_owned(self) -> KeyExpr<'static> { match self.0 { KeyExprInner::Borrowed(s) => KeyExpr(KeyExprInner::Owned(s.into())), @@ -211,6 +221,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 { @@ -236,6 +247,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) @@ -273,6 +285,7 @@ impl<'a> KeyExpr<'a> { } } + // tags{keyexpr.with_parameters} pub fn with_parameters(self, selector: &'a str) -> Selector<'a> { Selector { key_expr: self, @@ -280,6 +293,7 @@ impl<'a> KeyExpr<'a> { } } + // tags{keyexpr.with_parameters} pub fn with_owned_parameters(self, selector: String) -> Selector<'a> { Selector { key_expr: self, @@ -585,6 +599,7 @@ impl<'a> Undeclarable<&'a Session, KeyExprUndeclaration<'a>> for KeyExpr<'a> { /// session.undeclare(key_expr).res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[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..e34ff4d71d 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"); +// ignore_tagging pub const FEATURES: &str = concat_enabled_features!( prefix = "zenoh", features = [ @@ -160,6 +161,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{time.new_reception_timestamp} pub fn new_reception_timestamp() -> Timestamp { use std::time::{SystemTime, UNIX_EPOCH}; @@ -176,6 +178,7 @@ pub mod properties { /// Convert a set of [`Properties`] into a [`Value`]. /// For instance, Properties: `[("k1", "v1"), ("k2, v2")]` /// is converted into Json: `{ "k1": "v1", "k2": "v2" }` + // tags{properties.properties_to_json_value} pub fn properties_to_json_value(props: &Properties) -> Value { let json_map = props .iter() @@ -214,6 +217,7 @@ pub mod scouting; /// } /// # }) /// ``` +// tags{scout} pub fn scout, TryIntoConfig>( what: I, config: TryIntoConfig, @@ -257,6 +261,7 @@ where /// let session = zenoh::open(config).res().await.unwrap(); /// # }) /// ``` +// tags{session.open} pub fn open(config: TryIntoConfig) -> OpenBuilder where TryIntoConfig: std::convert::TryInto + Send + 'static, @@ -275,6 +280,7 @@ where /// let session = zenoh::open(config::peer()).res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct OpenBuilder where @@ -320,6 +326,7 @@ where /// Initialize a Session with an existing Runtime. /// This operation is used by the plugins to share the same Runtime as the router. +// ignore_tagging #[doc(hidden)] #[zenoh_macros::unstable] pub fn init(runtime: Runtime) -> InitBuilder { @@ -331,6 +338,7 @@ pub fn init(runtime: Runtime) -> InitBuilder { } /// A builder returned by [`init`] and used to initialize a Session with an existing Runtime. +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[doc(hidden)] #[zenoh_macros::unstable] @@ -343,12 +351,14 @@ pub struct InitBuilder { #[zenoh_macros::unstable] impl InitBuilder { #[inline] + // ignore_tagging pub fn aggregated_subscribers(mut self, exprs: Vec) -> Self { self.aggregated_subscribers = exprs; self } #[inline] + // ignore_tagging 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..3185db1866 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>, @@ -104,6 +105,7 @@ impl<'a> Liveliness<'a> { /// # }) /// ``` #[zenoh_macros::unstable] + // tags{liveliness.declare_token} pub fn declare_token<'b, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, @@ -139,6 +141,7 @@ impl<'a> Liveliness<'a> { /// } /// # }) /// ``` + // tags{liveliness.declare_subscriber} #[zenoh_macros::unstable] pub fn declare_subscriber<'b, TryIntoKeyExpr>( &self, @@ -175,6 +178,7 @@ impl<'a> Liveliness<'a> { /// } /// # }) /// ``` + // tags{liveliness.get} #[zenoh_macros::unstable] pub fn get<'b: 'a, TryIntoKeyExpr>( &'a self, @@ -214,6 +218,7 @@ impl<'a> Liveliness<'a> { /// .unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[zenoh_macros::unstable] #[derive(Debug)] @@ -288,6 +293,7 @@ pub(crate) struct LivelinessTokenState { /// .unwrap(); /// # }) /// ``` +// tags{liveliness.token} #[zenoh_macros::unstable] #[derive(Debug)] pub struct LivelinessToken<'a> { @@ -314,6 +320,7 @@ pub struct LivelinessToken<'a> { /// liveliness.undeclare().res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[zenoh_macros::unstable] pub struct LivelinessTokenUndeclaration<'a> { @@ -366,6 +373,7 @@ impl<'a> LivelinessToken<'a> { /// liveliness.undeclare().res().await.unwrap(); /// # }) /// ``` + // tags{liveliness.token.undeclare} #[inline] pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self, ()) @@ -405,6 +413,7 @@ impl Drop for LivelinessToken<'_> { /// .unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[zenoh_macros::unstable] #[derive(Debug)] @@ -432,6 +441,7 @@ impl<'a, 'b> LivelinessSubscriberBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{liveliness.subscriber.callback} #[inline] #[zenoh_macros::unstable] pub fn callback( @@ -473,6 +483,7 @@ impl<'a, 'b> LivelinessSubscriberBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{liveliness.subscriber.callback} #[inline] #[zenoh_macros::unstable] pub fn callback_mut( @@ -504,6 +515,7 @@ impl<'a, 'b> LivelinessSubscriberBuilder<'a, 'b, DefaultHandler> { /// } /// # }) /// ``` + // tags{liveliness.subscriber.pipe} #[inline] #[zenoh_macros::unstable] pub fn with(self, handler: Handler) -> LivelinessSubscriberBuilder<'a, 'b, Handler> @@ -600,6 +612,7 @@ where /// } /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct LivelinessGetBuilder<'a, 'b, Handler> { @@ -627,6 +640,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{liveiness.get.callback} #[inline] pub fn callback(self, callback: Callback) -> LivelinessGetBuilder<'a, 'b, Callback> where @@ -667,6 +681,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{liveiness.get.callback} #[inline] pub fn callback_mut( self, @@ -698,6 +713,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// } /// # }) /// ``` + // tags{liveiness.get.pipe} #[inline] pub fn with(self, handler: Handler) -> LivelinessGetBuilder<'a, 'b, Handler> where @@ -720,6 +736,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { impl<'a, 'b, Handler> LivelinessGetBuilder<'a, 'b, Handler> { /// Set query timeout. + // tags{liveiness.get.timeout} #[inline] pub fn timeout(mut self, timeout: Duration) -> Self { self.timeout = timeout; diff --git a/zenoh/src/net/codec/mod.rs b/zenoh/src/net/codec/mod.rs index 06154cd02c..be69eafd48 100644 --- a/zenoh/src/net/codec/mod.rs +++ b/zenoh/src/net/codec/mod.rs @@ -13,10 +13,12 @@ // pub(crate) mod linkstate; +// ignore_tagging #[derive(Clone, Copy)] pub struct Zenoh080Routing; impl Zenoh080Routing { + // ignore_tagging pub const fn new() -> Self { Self } diff --git a/zenoh/src/net/routing/face.rs b/zenoh/src/net/routing/face.rs index 90946527ee..c9a2a30630 100644 --- a/zenoh/src/net/routing/face.rs +++ b/zenoh/src/net/routing/face.rs @@ -27,6 +27,7 @@ use zenoh_protocol::{ use zenoh_transport::stats::TransportStats; use zenoh_transport::{multicast::TransportMulticast, primitives::Primitives}; +// ignore_tagging pub struct FaceState { pub(super) id: usize, pub(super) zid: ZenohId, @@ -83,6 +84,7 @@ impl FaceState { #[allow(dead_code)] #[inline] + // ignore_tagging pub fn is_local(&self) -> bool { self.local } @@ -159,6 +161,7 @@ impl fmt::Display for FaceState { } } +// ignore_tagging #[derive(Clone)] pub struct Face { pub(crate) tables: Arc, diff --git a/zenoh/src/net/routing/router.rs b/zenoh/src/net/routing/router.rs index 933bd7339c..f5a31b39a1 100644 --- a/zenoh/src/net/routing/router.rs +++ b/zenoh/src/net/routing/router.rs @@ -76,6 +76,7 @@ impl<'a> RoutingExpr<'a> { } } +// ignore_tagging pub struct Tables { pub(crate) zid: ZenohId, pub(crate) whatami: WhatAmI, diff --git a/zenoh/src/net/tests/tables.rs b/zenoh/src/net/tests/tables.rs index 518ec7e551..4477a198bc 100644 --- a/zenoh/src/net/tests/tables.rs +++ b/zenoh/src/net/tests/tables.rs @@ -373,7 +373,7 @@ fn clean_test() { assert!(res3.upgrade().is_none()); } -pub struct ClientPrimitives { +pub(crate) struct ClientPrimitives { data: std::sync::Mutex>>, mapping: std::sync::Mutex>, } diff --git a/zenoh/src/publication.rs b/zenoh/src/publication.rs index d8d0e26ad9..fc3f35dd69 100644 --- a/zenoh/src/publication.rs +++ b/zenoh/src/publication.rs @@ -74,6 +74,7 @@ pub type DeleteBuilder<'a, 'b> = PutBuilder<'a, 'b>; /// .unwrap(); /// # }) /// ``` +/// tags{session.put} #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug, Clone)] pub struct PutBuilder<'a, 'b> { From c5ad4d7da79a9b9bae46a6380c15b01e90c1ce96 Mon Sep 17 00:00:00 2001 From: Michael Ilyin Date: Mon, 5 Feb 2024 01:04:43 +0100 Subject: [PATCH 3/5] more tagging --- commons/zenoh-protocol/src/core/mod.rs | 2 ++ zenoh/src/net/codec/mod.rs | 1 + zenoh/src/net/protocol/mod.rs | 1 + zenoh/src/net/routing/face.rs | 2 ++ zenoh/src/net/routing/mod.rs | 14 +++++---- zenoh/src/net/routing/pubsub.rs | 14 ++++----- zenoh/src/net/routing/queries.rs | 14 ++++----- zenoh/src/net/routing/router.rs | 1 - zenoh/src/net/runtime/mod.rs | 16 +++++++++- zenoh/src/net/tests/mod.rs | 1 + zenoh/src/net/tests/tables.rs | 1 + zenoh/src/plugins/mod.rs | 1 + zenoh/src/publication.rs | 43 +++++++++++++++++++++++++- zenoh/src/query.rs | 18 +++++++++++ zenoh/src/queryable.rs | 19 ++++++++++++ zenoh/src/sample.rs | 26 ++++++++++++++++ zenoh/src/scouting.rs | 8 ++++- 17 files changed, 158 insertions(+), 24 deletions(-) diff --git a/commons/zenoh-protocol/src/core/mod.rs b/commons/zenoh-protocol/src/core/mod.rs index bb76cea913..c7aac86703 100644 --- a/commons/zenoh-protocol/src/core/mod.rs +++ b/commons/zenoh-protocol/src/core/mod.rs @@ -61,6 +61,7 @@ pub struct Property { } /// The kind of a `Sample`. +// tags{sample.kind} #[repr(u8)] #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] pub enum SampleKind { @@ -424,6 +425,7 @@ pub enum ConsolidationMode { } /// The `zenoh::queryable::Queryable`s that should be target of a `zenoh::Session::get()`. +// tags{session.query.target} #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] pub enum QueryTarget { #[default] diff --git a/zenoh/src/net/codec/mod.rs b/zenoh/src/net/codec/mod.rs index be69eafd48..846d224139 100644 --- a/zenoh/src/net/codec/mod.rs +++ b/zenoh/src/net/codec/mod.rs @@ -11,6 +11,7 @@ // Contributors: // ZettaScale Zenoh Team, // +// ignore_tagging pub(crate) mod linkstate; // ignore_tagging diff --git a/zenoh/src/net/protocol/mod.rs b/zenoh/src/net/protocol/mod.rs index 7343a07fd0..a00abbf8ae 100644 --- a/zenoh/src/net/protocol/mod.rs +++ b/zenoh/src/net/protocol/mod.rs @@ -11,4 +11,5 @@ // Contributors: // ZettaScale Zenoh Team, // +// ignore_tagging pub(crate) mod linkstate; diff --git a/zenoh/src/net/routing/face.rs b/zenoh/src/net/routing/face.rs index c9a2a30630..cfe5daec7e 100644 --- a/zenoh/src/net/routing/face.rs +++ b/zenoh/src/net/routing/face.rs @@ -11,6 +11,8 @@ // Contributors: // ZettaScale Zenoh Team, // +use super::pubsub::*; +use super::queries::*; use super::router::*; use std::collections::{HashMap, HashSet}; use std::fmt; diff --git a/zenoh/src/net/routing/mod.rs b/zenoh/src/net/routing/mod.rs index 886b0b50dc..59c2a7cd06 100644 --- a/zenoh/src/net/routing/mod.rs +++ b/zenoh/src/net/routing/mod.rs @@ -17,12 +17,14 @@ //! This module is intended for Zenoh's internal use. //! //! [Click here for Zenoh's documentation](../zenoh/index.html) -pub mod face; -pub mod network; -pub mod pubsub; -pub mod queries; -pub mod resource; -pub mod router; +pub(crate) mod face; +pub(crate) mod network; +pub(crate) mod pubsub; +pub(crate) mod queries; +// ignore_tagging +pub(crate) mod resource; +// ignore_tagging +pub(crate) mod router; use super::runtime; diff --git a/zenoh/src/net/routing/pubsub.rs b/zenoh/src/net/routing/pubsub.rs index c7a913bc29..87001e1ad7 100644 --- a/zenoh/src/net/routing/pubsub.rs +++ b/zenoh/src/net/routing/pubsub.rs @@ -222,7 +222,7 @@ fn register_router_subscription( propagate_simple_subscription(tables, res, sub_info, face); } -pub fn declare_router_subscription( +pub(crate) fn declare_router_subscription( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -404,7 +404,7 @@ fn register_client_subscription( get_mut_unchecked(face).remote_subs.insert(res.clone()); } -pub fn declare_client_subscription( +pub(crate) fn declare_client_subscription( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -717,7 +717,7 @@ fn undeclare_router_subscription( } } -pub fn forget_router_subscription( +pub(crate) fn forget_router_subscription( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -783,7 +783,7 @@ fn undeclare_peer_subscription( } } -pub fn forget_peer_subscription( +pub(crate) fn forget_peer_subscription( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -884,7 +884,7 @@ pub(crate) fn undeclare_client_subscription( } } -pub fn forget_client_subscription( +pub(crate) fn forget_client_subscription( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -1750,7 +1750,7 @@ macro_rules! inc_stats { } #[allow(clippy::too_many_arguments)] -pub fn full_reentrant_route_data( +pub(crate) fn full_reentrant_route_data( tables_ref: &RwLock, face: &FaceState, expr: &WireExpr, @@ -1894,7 +1894,7 @@ pub fn full_reentrant_route_data( } } -pub fn pull_data(tables_ref: &RwLock, face: &Arc, expr: WireExpr) { +pub(crate) fn pull_data(tables_ref: &RwLock, face: &Arc, expr: WireExpr) { let tables = zread!(tables_ref); match tables.get_mapping(face, &expr.scope, expr.mapping) { Some(prefix) => match Resource::get_resource(prefix, expr.suffix.as_ref()) { diff --git a/zenoh/src/net/routing/queries.rs b/zenoh/src/net/routing/queries.rs index c2496b5ff8..25f062edd7 100644 --- a/zenoh/src/net/routing/queries.rs +++ b/zenoh/src/net/routing/queries.rs @@ -383,7 +383,7 @@ fn register_router_queryable( propagate_simple_queryable(tables, res, face); } -pub fn declare_router_queryable( +pub(crate) fn declare_router_queryable( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -473,7 +473,7 @@ fn register_peer_queryable( } } -pub fn declare_peer_queryable( +pub(crate) fn declare_peer_queryable( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -558,7 +558,7 @@ fn register_client_queryable( get_mut_unchecked(face).remote_qabls.insert(res.clone()); } -pub fn declare_client_queryable( +pub(crate) fn declare_client_queryable( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -843,7 +843,7 @@ fn undeclare_router_queryable( } } -pub fn forget_router_queryable( +pub(crate) fn forget_router_queryable( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -903,7 +903,7 @@ fn undeclare_peer_queryable( } } -pub fn forget_peer_queryable( +pub(crate) fn forget_peer_queryable( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -1018,7 +1018,7 @@ pub(crate) fn undeclare_client_queryable( } } -pub fn forget_client_queryable( +pub(crate) fn forget_client_queryable( tables: &TablesLock, rtables: RwLockReadGuard, face: &mut Arc, @@ -2060,7 +2060,7 @@ macro_rules! inc_res_stats { } #[allow(clippy::too_many_arguments)] -pub fn route_query( +pub(crate) fn route_query( tables_ref: &Arc, face: &Arc, expr: &WireExpr, diff --git a/zenoh/src/net/routing/router.rs b/zenoh/src/net/routing/router.rs index f5a31b39a1..933bd7339c 100644 --- a/zenoh/src/net/routing/router.rs +++ b/zenoh/src/net/routing/router.rs @@ -76,7 +76,6 @@ impl<'a> RoutingExpr<'a> { } } -// ignore_tagging pub struct Tables { pub(crate) zid: ZenohId, pub(crate) whatami: WhatAmI, diff --git a/zenoh/src/net/runtime/mod.rs b/zenoh/src/net/runtime/mod.rs index 8eb57699b8..77b76fa5ff 100644 --- a/zenoh/src/net/runtime/mod.rs +++ b/zenoh/src/net/runtime/mod.rs @@ -17,8 +17,11 @@ //! This module is intended for Zenoh's internal use. //! //! [Click here for Zenoh's documentation](../zenoh/index.html) + +// ignore_tagging mod adminspace; -pub mod orchestrator; +// ignore_tagging +pub(crate) mod orchestrator; use super::routing; use super::routing::face::Face; @@ -61,6 +64,7 @@ struct RuntimeState { stop_source: std::sync::RwLock>, } +// ignore_tagging #[derive(Clone)] pub struct Runtime { state: Arc, @@ -78,6 +82,7 @@ impl StructVersion for Runtime { impl PluginStartArgs for Runtime {} impl Runtime { + // ignore_tagging pub async fn new(config: Config) -> ZResult { let mut runtime = Runtime::init(config).await?; match runtime.start().await { @@ -182,14 +187,17 @@ impl Runtime { } #[inline(always)] + // ignore_tagging pub fn manager(&self) -> &TransportManager { &self.state.manager } + // ignore_tagging pub fn new_handler(&self, handler: Arc) { zwrite!(self.state.transport_handlers).push(handler); } + // ignore_tagging pub async fn close(&self) -> ZResult<()> { log::trace!("Runtime::close())"); drop(self.state.stop_source.write().unwrap().take()); @@ -197,10 +205,12 @@ impl Runtime { Ok(()) } + // ignore_tagging pub fn new_timestamp(&self) -> Option { self.state.hlc.as_ref().map(|hlc| hlc.new_timestamp()) } + // ignore_tagging pub fn get_locators(&self) -> Vec { self.state.locators.read().unwrap().clone() } @@ -222,18 +232,22 @@ impl Runtime { self.state.router.clone() } + // ignore_tagging pub fn config(&self) -> &Notifier { &self.state.config } + // ignore_tagging pub fn hlc(&self) -> Option<&HLC> { self.state.hlc.as_ref().map(Arc::as_ref) } + // ignore_tagging pub fn zid(&self) -> ZenohId { self.state.zid } + // ignore_tagging pub fn whatami(&self) -> WhatAmI { self.state.whatami } diff --git a/zenoh/src/net/tests/mod.rs b/zenoh/src/net/tests/mod.rs index b8b42bef12..43eba636a1 100644 --- a/zenoh/src/net/tests/mod.rs +++ b/zenoh/src/net/tests/mod.rs @@ -1 +1,2 @@ +// ignore_tagging pub(crate) mod tables; diff --git a/zenoh/src/net/tests/tables.rs b/zenoh/src/net/tests/tables.rs index 4477a198bc..4e959c3c4f 100644 --- a/zenoh/src/net/tests/tables.rs +++ b/zenoh/src/net/tests/tables.rs @@ -11,6 +11,7 @@ // Contributors: // ZettaScale Zenoh Team, // +use crate::net::routing::pubsub::*; use crate::net::routing::router::{self, *}; use std::convert::{TryFrom, TryInto}; use std::sync::{Arc, Mutex, RwLock}; diff --git a/zenoh/src/plugins/mod.rs b/zenoh/src/plugins/mod.rs index d72139cc29..fbd0066235 100644 --- a/zenoh/src/plugins/mod.rs +++ b/zenoh/src/plugins/mod.rs @@ -17,6 +17,7 @@ //! This module is intended for Zenoh's internal use. //! //! [Click here for Zenoh's documentation](../../zenoh/index.html) +// ignore_tagging pub(crate) mod sealed; #[zenoh_macros::unstable] diff --git a/zenoh/src/publication.rs b/zenoh/src/publication.rs index fc3f35dd69..b2503999f9 100644 --- a/zenoh/src/publication.rs +++ b/zenoh/src/publication.rs @@ -74,7 +74,7 @@ pub type DeleteBuilder<'a, 'b> = PutBuilder<'a, 'b>; /// .unwrap(); /// # }) /// ``` -/// tags{session.put} +/// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug, Clone)] pub struct PutBuilder<'a, 'b> { @@ -87,6 +87,7 @@ pub struct PutBuilder<'a, 'b> { impl PutBuilder<'_, '_> { /// Change the encoding of the written data. + // tags{session.put.encoding} #[inline] pub fn encoding(mut self, encoding: IntoEncoding) -> Self where @@ -96,6 +97,7 @@ impl PutBuilder<'_, '_> { self } /// Change the `congestion_control` to apply when routing the data. + // tags{session.put.congestion_control} #[inline] pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.publisher = self.publisher.congestion_control(congestion_control); @@ -103,6 +105,7 @@ impl PutBuilder<'_, '_> { } /// Change the priority of the written data. + // tags{session.put.priority} #[inline] pub fn priority(mut self, priority: Priority) -> Self { self.publisher = self.publisher.priority(priority); @@ -111,6 +114,7 @@ impl PutBuilder<'_, '_> { /// Restrict the matching subscribers that will receive the published data /// to the ones that have the given [`Locality`](crate::prelude::Locality). + // tags{session.put.allowed_destination} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -118,12 +122,14 @@ impl PutBuilder<'_, '_> { self } + // tags{session.put.kind} pub fn kind(mut self, kind: SampleKind) -> Self { self.kind = kind; self } #[zenoh_macros::unstable] + // tags{session.put.attachment} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self @@ -180,6 +186,7 @@ use zenoh_result::Error; #[zenoh_macros::unstable] #[derive(Clone)] +// ignore_tagging pub enum PublisherRef<'a> { Borrow(&'a Publisher<'a>), Shared(std::sync::Arc>), @@ -236,6 +243,7 @@ impl std::fmt::Debug for PublisherRef<'_> { /// subscriber.stream().map(Ok).forward(publisher).await.unwrap(); /// # }) /// ``` +// tags{session.publisher} #[derive(Debug, Clone)] pub struct Publisher<'a> { pub(crate) session: SessionRef<'a>, @@ -246,11 +254,13 @@ pub struct Publisher<'a> { } impl<'a> Publisher<'a> { + // tags{session.publisher.key_expr} pub fn key_expr(&self) -> &KeyExpr<'a> { &self.key_expr } /// Change the `congestion_control` to apply when routing the data. + // tags{session.publisher.congestion_control} #[inline] pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.congestion_control = congestion_control; @@ -258,6 +268,7 @@ impl<'a> Publisher<'a> { } /// Change the priority of the written data. + // tags{session.publisher.priority} #[inline] pub fn priority(mut self, priority: Priority) -> Self { self.priority = priority; @@ -266,6 +277,7 @@ impl<'a> Publisher<'a> { /// Restrict the matching subscribers that will receive the published data /// to the ones that have the given [`Locality`](crate::prelude::Locality). + // tags{session.publisher.allowed_destination} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -303,6 +315,7 @@ impl<'a> Publisher<'a> { /// }).await; /// # }) /// ``` + // ignore_tagging #[zenoh_macros::unstable] pub fn into_arc(self) -> std::sync::Arc { std::sync::Arc::new(self) @@ -330,6 +343,7 @@ impl<'a> Publisher<'a> { /// publisher.write(SampleKind::Put, "value").res().await.unwrap(); /// # }) /// ``` + // tags{session.publisher.write} pub fn write(&self, kind: SampleKind, value: IntoValue) -> Publication where IntoValue: Into, @@ -349,6 +363,7 @@ impl<'a> Publisher<'a> { /// publisher.put("value").res().await.unwrap(); /// # }) /// ``` + // tags{session.publisher.put} #[inline] pub fn put(&self, value: IntoValue) -> Publication where @@ -369,6 +384,7 @@ impl<'a> Publisher<'a> { /// publisher.delete().res().await.unwrap(); /// # }) /// ``` + // tags{session.publisher.delete} pub fn delete(&self) -> Publication { self._write(SampleKind::Delete, Value::empty()) } @@ -393,6 +409,7 @@ impl<'a> Publisher<'a> { /// .matching_subscribers(); /// # }) /// ``` + // tags{session.publisher.matching_status} #[zenoh_macros::unstable] pub fn matching_status(&self) -> impl Resolve> + '_ { zenoh_core::ResolveFuture::new(async move { @@ -423,6 +440,7 @@ impl<'a> Publisher<'a> { /// } /// # }) /// ``` + // tags{session.publisher.matching_listener} #[zenoh_macros::unstable] pub fn matching_listener(&self) -> MatchingListenerBuilder<'_, DefaultHandler> { MatchingListenerBuilder { @@ -443,6 +461,7 @@ impl<'a> Publisher<'a> { /// publisher.undeclare().res().await.unwrap(); /// # }) /// ``` + // tags{session.publisher.undeclare} pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self, ()) } @@ -476,6 +495,7 @@ impl<'a> Publisher<'a> { /// }).await; /// # }) /// ``` +// ignore_tagging #[zenoh_macros::unstable] pub trait PublisherDeclarations { /// # Examples @@ -551,6 +571,7 @@ impl<'a> Undeclarable<(), PublisherUndeclaration<'a>> for Publisher<'a> { /// publisher.undeclare().res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct PublisherUndeclaration<'a> { publisher: Publisher<'a>, @@ -594,6 +615,7 @@ impl Drop for Publisher<'_> { /// A [`Resolvable`] returned by [`Publisher::put()`](Publisher::put), /// [`Publisher::delete()`](Publisher::delete) and [`Publisher::write()`](Publisher::write). +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct Publication<'a> { publisher: &'a Publisher<'a>, @@ -604,6 +626,7 @@ pub struct Publication<'a> { } impl<'a> Publication<'a> { + // tags{session.publisher.put.attachment} #[zenoh_macros::unstable] pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); @@ -679,6 +702,7 @@ where /// .unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct PublisherBuilder<'a, 'b: 'a> { @@ -706,6 +730,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. + // tags{session.publisher.congestion_control} #[inline] pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.congestion_control = congestion_control; @@ -713,6 +738,7 @@ impl<'a, 'b> PublisherBuilder<'a, 'b> { } /// Change the priority of the written data. + // tags{session.publisher.priority} #[inline] pub fn priority(mut self, priority: Priority) -> Self { self.priority = priority; @@ -721,6 +747,7 @@ impl<'a, 'b> PublisherBuilder<'a, 'b> { /// Restrict the matching subscribers that will receive the published data /// to the ones that have the given [`Locality`](crate::prelude::Locality). + // tags{session.publisher.allowed_destination} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -874,6 +901,7 @@ fn resolve_put( } /// The Priority of zenoh messages. +// tags{session.put.priority} #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] pub enum Priority { @@ -889,10 +917,13 @@ pub enum Priority { impl Priority { /// The lowest Priority + // tags{session.put.priority.min} pub const MIN: Self = Self::Background; /// The highest Priority + // tags{session.put.priority.max} pub const MAX: Self = Self::RealTime; /// The number of available priorities + // tags{session.put.priority.num} pub const NUM: usize = 1 + Self::MIN as usize - Self::MAX as usize; } @@ -952,6 +983,7 @@ impl From for zenoh_protocol::core::Priority { /// let matching_status = publisher.matching_status().res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[zenoh_macros::unstable] #[derive(Copy, Clone, Debug)] pub struct MatchingStatus { @@ -977,12 +1009,14 @@ impl MatchingStatus { /// .matching_subscribers(); /// # }) /// ``` + /// tags{session.publisher.matching_status.matching_subscribers^} pub fn matching_subscribers(&self) -> bool { self.matching } } /// A builder for initializing a [`MatchingListener`]. +// ignore_tagging #[zenoh_macros::unstable] #[derive(Debug)] pub struct MatchingListenerBuilder<'a, Handler> { @@ -1015,6 +1049,7 @@ impl<'a> MatchingListenerBuilder<'a, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // ignore_tagging #[inline] #[zenoh_macros::unstable] pub fn callback(self, callback: Callback) -> MatchingListenerBuilder<'a, Callback> @@ -1049,6 +1084,7 @@ impl<'a> MatchingListenerBuilder<'a, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // ignore_tagging #[inline] #[zenoh_macros::unstable] pub fn callback_mut( @@ -1085,6 +1121,7 @@ impl<'a> MatchingListenerBuilder<'a, DefaultHandler> { /// } /// # }) /// ``` + // ignore_tagging #[inline] #[zenoh_macros::unstable] pub fn with(self, handler: Handler) -> MatchingListenerBuilder<'a, Handler> @@ -1174,6 +1211,7 @@ pub(crate) struct MatchingListenerInner<'a> { #[zenoh_macros::unstable] impl<'a> MatchingListenerInner<'a> { #[inline] + // ignore_tagging pub fn undeclare(self) -> MatchingListenerUndeclaration<'a> { Undeclarable::undeclare_inner(self, ()) } @@ -1206,6 +1244,7 @@ impl<'a> Undeclarable<(), MatchingListenerUndeclaration<'a>> for MatchingListene /// } /// # }) /// ``` +// tags{session.publisher.matching_listener} #[zenoh_macros::unstable] pub struct MatchingListener<'a, Receiver> { pub(crate) listener: MatchingListenerInner<'a>, @@ -1230,6 +1269,7 @@ impl<'a, Receiver> MatchingListener<'a, Receiver> { /// matching_listener.undeclare().res().await.unwrap(); /// # }) /// ``` + // tags{session.publisher.matching_listener.undeclare} #[inline] pub fn undeclare(self) -> MatchingListenerUndeclaration<'a> { self.listener.undeclare() @@ -1258,6 +1298,7 @@ impl std::ops::DerefMut for MatchingListener<'_, Receiver> { } } +// ignore_tagging #[zenoh_macros::unstable] pub struct MatchingListenerUndeclaration<'a> { subscriber: MatchingListenerInner<'a>, diff --git a/zenoh/src/query.rs b/zenoh/src/query.rs index c4f3fb35e9..bfac886cb4 100644 --- a/zenoh/src/query.rs +++ b/zenoh/src/query.rs @@ -32,6 +32,7 @@ pub use zenoh_protocol::core::QueryTarget; pub use zenoh_protocol::core::ConsolidationMode; /// The operation: either manual or automatic. +// ignore_tagging #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Mode { Auto, @@ -39,6 +40,7 @@ pub enum Mode { } /// The replies consolidation strategy to apply on replies to a [`get`](Session::get). +// tags{session.get.consolidation_mode} #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct QueryConsolidation { pub(crate) mode: Mode, @@ -46,6 +48,7 @@ pub struct QueryConsolidation { impl QueryConsolidation { /// Automatic query consolidation strategy selection. + // tags{session.get.consolidation_mode.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`]. + // ignore_tagging pub fn mode(&self) -> Mode { self.mode } @@ -77,6 +81,7 @@ impl Default for QueryConsolidation { } /// Structs returned by a [`get`](Session::get). +// tags{session.get.reply} #[non_exhaustive] #[derive(Clone, Debug)] pub struct Reply { @@ -116,6 +121,7 @@ pub(crate) struct QueryState { /// } /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct GetBuilder<'a, 'b, Handler> { @@ -149,6 +155,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{session.get.callback} #[inline] pub fn callback(self, callback: Callback) -> GetBuilder<'a, 'b, Callback> where @@ -202,6 +209,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{session.get.callback} #[inline] pub fn callback_mut( self, @@ -232,6 +240,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// } /// # }) /// ``` + // tags{session.get.pipe} #[inline] pub fn with(self, handler: Handler) -> GetBuilder<'a, 'b, Handler> where @@ -267,6 +276,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { } impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Change the target of the query. + // tags{session.get.target} #[inline] pub fn target(mut self, target: QueryTarget) -> Self { self.target = target; @@ -274,6 +284,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } /// Change the consolidation mode of the query. + // tags{session.get.consolidation_mode} #[inline] pub fn consolidation>(mut self, consolidation: QC) -> Self { self.consolidation = consolidation.into(); @@ -282,6 +293,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Restrict the matching queryables that will receive the query /// to the ones that have the given [`Locality`](crate::prelude::Locality). + // tags{session.get.allowed_destination} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -290,6 +302,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } /// Set query timeout. + // tags{session.get.timeout} #[inline] pub fn timeout(mut self, timeout: Duration) -> Self { self.timeout = timeout; @@ -297,6 +310,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } /// Set query value. + // tags{session.get.value} #[inline] pub fn with_value(mut self, value: IntoValue) -> Self where @@ -307,6 +321,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } #[zenoh_macros::unstable] + // tags{session.get.attachment} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self @@ -317,6 +332,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. + // tags{session.get.accept_replies} #[zenoh_macros::unstable] pub fn accept_replies(self, accept: ReplyKeyExpr) -> Self { let Self { @@ -348,10 +364,12 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { pub(crate) const _REPLY_KEY_EXPR_ANY_SEL_PARAM: &str = "_anyke"; #[zenoh_macros::unstable] +// tags{session.get.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{session.get.accept_replies} pub enum ReplyKeyExpr { Any, MatchingQuery, diff --git a/zenoh/src/queryable.rs b/zenoh/src/queryable.rs index b602ba670b..b9960df82d 100644 --- a/zenoh/src/queryable.rs +++ b/zenoh/src/queryable.rs @@ -63,6 +63,7 @@ impl Drop for QueryInner { } /// Structs received by a [`Queryable`]. +// tags{session.queryable} #[derive(Clone)] pub struct Query { pub(crate) inner: Arc, @@ -70,6 +71,7 @@ pub struct Query { impl Query { /// The full [`Selector`] of this Query. + // tags{session.queryable.selector} #[inline(always)] pub fn selector(&self) -> Selector<'_> { Selector { @@ -79,23 +81,27 @@ impl Query { } /// The key selector part of this Query. + // tags{session.queryable.selector.key_expr} #[inline(always)] pub fn key_expr(&self) -> &KeyExpr<'static> { &self.inner.key_expr } /// This Query's selector parameters. + // tags{session.queryable.selector.parameters} #[inline(always)] pub fn parameters(&self) -> &str { &self.inner.parameters } /// This Query's value. + // tags{session.queryable.value} #[inline(always)] pub fn value(&self) -> Option<&Value> { self.inner.value.as_ref() } + // tags{session.queryable.attachment} #[zenoh_macros::unstable] pub fn attachment(&self) -> Option<&Attachment> { self.inner.attachment.as_ref() @@ -106,6 +112,7 @@ impl Query { /// By default, queries only accept replies whose key expression intersects with the query's. /// 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. + // tags{session.queryable.reply} #[inline(always)] pub fn reply(&self, result: Result) -> ReplyBuilder<'_> { ReplyBuilder { @@ -116,6 +123,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. + // tags{session.queryable.accepts_replies} #[zenoh_macros::unstable] pub fn accepts_replies(&self) -> ZResult { self._accepts_any_replies().map(|any| { @@ -154,6 +162,7 @@ impl fmt::Display for Query { } /// A builder returned by [`Query::reply()`](Query::reply). +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct ReplyBuilder<'a> { @@ -164,6 +173,7 @@ pub struct ReplyBuilder<'a> { impl<'a> ReplyBuilder<'a> { #[allow(clippy::result_large_err)] #[zenoh_macros::unstable] + // tags{session.queryable.reply.attachment} pub fn with_attachment(mut self, attachment: Attachment) -> Result { match &mut self.result { Ok(sample) => { @@ -363,6 +373,7 @@ impl<'a> Undeclarable<(), QueryableUndeclaration<'a>> for CallbackQueryable<'a> /// queryable.undeclare().res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct QueryableUndeclaration<'a> { queryable: CallbackQueryable<'a>, @@ -409,6 +420,7 @@ impl Drop for CallbackQueryable<'_> { /// let queryable = session.declare_queryable("key/expression").res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct QueryableBuilder<'a, 'b, Handler> { @@ -436,6 +448,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{session.queryable.callback} #[inline] pub fn callback(self, callback: Callback) -> QueryableBuilder<'a, 'b, Callback> where @@ -477,6 +490,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` + // tags{session.queryable.callback} #[inline] pub fn callback_mut( self, @@ -507,6 +521,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// } /// # }) /// ``` + // tags{session.queryable.pipe} #[inline] pub fn with(self, handler: Handler) -> QueryableBuilder<'a, 'b, Handler> where @@ -530,6 +545,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// Restrict the matching queries that will be receive by this [`Queryable`] /// to the ones that have the given [`Locality`](crate::prelude::Locality). + // tags{session.queryable.allowed_origin} #[inline] #[zenoh_macros::unstable] pub fn allowed_origin(mut self, origin: Locality) -> Self { @@ -539,6 +555,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { } impl<'a, 'b, Handler> QueryableBuilder<'a, 'b, Handler> { /// Change queryable completeness. + // tags{session.queryable.complete} #[inline] pub fn complete(mut self, complete: bool) -> Self { self.complete = complete; @@ -576,6 +593,7 @@ impl<'a, 'b, Handler> QueryableBuilder<'a, 'b, Handler> { /// } /// # }) /// ``` +// ignore_tagging #[non_exhaustive] #[derive(Debug)] pub struct Queryable<'a, Receiver> { @@ -585,6 +603,7 @@ pub struct Queryable<'a, Receiver> { impl<'a, Receiver> Queryable<'a, Receiver> { #[inline] + // tags{session.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 46e73b01f0..456fe93a52 100644 --- a/zenoh/src/sample.rs +++ b/zenoh/src/sample.rs @@ -54,6 +54,7 @@ pub(crate) struct DataInfo { } /// Informations on the source of a zenoh [`Sample`]. +// tags{sample.source_info} #[zenoh_macros::unstable] #[derive(Debug, Clone)] pub struct SourceInfo { @@ -112,6 +113,7 @@ mod attachment { use zenoh_protocol::zenoh::ext::AttachmentType; /// A builder for [`Attachment`] + // ignore_tagging #[zenoh_macros::unstable] #[derive(Debug)] pub struct AttachmentBuilder { @@ -125,6 +127,7 @@ mod attachment { } #[zenoh_macros::unstable] impl AttachmentBuilder { + // ignore_tagging pub fn new() -> Self { Self { inner: Vec::new() } } @@ -137,6 +140,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, @@ -144,6 +148,7 @@ mod attachment { ) { self._insert(key.as_ref(), value.as_ref()) } + // ignore_tagging pub fn build(self) -> Attachment { Attachment { inner: self.inner.into(), @@ -158,6 +163,7 @@ mod attachment { } } } + // tags{sample.attachment} #[zenoh_macros::unstable] #[derive(Clone)] pub struct Attachment { @@ -183,17 +189,21 @@ mod attachment { } #[zenoh_macros::unstable] impl Attachment { + // tags{sample.attachment.new} pub fn new() -> Self { Self { inner: ZBuf::empty(), } } + // tags{sample.attachment.is_empty} pub fn is_empty(&self) -> bool { self.len() == 0 } + // tags{sample.attachment.len} pub fn len(&self) -> usize { self.iter().count() } + // ignore_tagging pub fn iter(&self) -> AttachmentIterator { self.into_iter() } @@ -201,6 +211,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()) } @@ -215,6 +226,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, @@ -228,11 +240,13 @@ mod attachment { } self } + // tags{sample.attachment.extend} pub fn extend(&mut self, with: impl Into) -> &mut Self { let with = with.into(); self._extend(with) } } + // ignore_tagging #[zenoh_macros::unstable] pub struct AttachmentIterator<'a> { reader: ZBufReader<'a>, @@ -312,10 +326,12 @@ mod attachment { } } } + #[zenoh_macros::unstable] pub use attachment::{Attachment, AttachmentBuilder, AttachmentIterator}; /// A zenoh sample. +// tags{sample} #[non_exhaustive] #[derive(Clone, Debug)] pub struct Sample { @@ -351,6 +367,7 @@ pub struct Sample { impl Sample { /// Creates a new Sample. + // tags{sample.new} #[inline] pub fn new(key_expr: IntoKeyExpr, value: IntoValue) -> Self where @@ -369,6 +386,7 @@ impl Sample { } } /// Creates a new Sample. + // tags{sample.from_value} #[inline] pub fn try_from( key_expr: TryIntoKeyExpr, @@ -392,6 +410,7 @@ impl Sample { } /// Creates a new Sample with optional data info. + // tags{sample.with_info} #[inline] pub(crate) fn with_info( key_expr: KeyExpr<'static>, @@ -428,12 +447,14 @@ impl Sample { } /// Gets the timestamp of this Sample. + // tags{sample.get_timestamp} #[inline] pub fn get_timestamp(&self) -> Option<&Timestamp> { self.timestamp.as_ref() } /// Sets the timestamp of this Sample. + // tags{sample.with_timestamp} #[inline] pub fn with_timestamp(mut self, timestamp: Timestamp) -> Self { self.timestamp = Some(timestamp); @@ -441,6 +462,7 @@ impl Sample { } /// Sets the source info of this Sample. + // tags{sample.with_source_info} #[zenoh_macros::unstable] #[inline] pub fn with_source_info(mut self, source_info: SourceInfo) -> Self { @@ -452,6 +474,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.ensure_timestamp} pub fn ensure_timestamp(&mut self) -> &Timestamp { if let Some(ref timestamp) = self.timestamp { timestamp @@ -463,17 +486,20 @@ impl Sample { } #[zenoh_macros::unstable] + // tags{sample.get_attachment} pub fn attachment(&self) -> Option<&Attachment> { self.attachment.as_ref() } #[zenoh_macros::unstable] + // tags{sample.get_attachment_mut} pub fn attachment_mut(&mut self) -> &mut Option { &mut self.attachment } #[allow(clippy::result_large_err)] #[zenoh_macros::unstable] + // tags{sample.with_attachment} 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..1633f02440 100644 --- a/zenoh/src/scouting.rs +++ b/zenoh/src/scouting.rs @@ -44,6 +44,7 @@ pub use zenoh_protocol::scouting::Hello; /// } /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct ScoutBuilder { @@ -68,6 +69,7 @@ impl ScoutBuilder { /// .unwrap(); /// # }) /// ``` + // tags{scout.callback} #[inline] pub fn callback(self, callback: Callback) -> ScoutBuilder where @@ -104,6 +106,7 @@ impl ScoutBuilder { /// .unwrap(); /// # }) /// ``` + /// tags{scout.callback} #[inline] pub fn callback_mut( self, @@ -133,6 +136,7 @@ impl ScoutBuilder { /// } /// # }) /// ``` + // tags{scout.pipe} #[inline] pub fn with(self, handler: Handler) -> ScoutBuilder where @@ -219,7 +223,7 @@ impl ScoutInner { /// scout.stop(); /// # }) /// ``` - pub fn stop(self) { + pub(crate) fn stop(self) { // This drops the inner `stop_sender` and hence stops the scouting receiver std::mem::drop(self); } @@ -249,6 +253,7 @@ impl fmt::Debug for ScoutInner { /// } /// # }) /// ``` +// tags{scout} #[non_exhaustive] #[derive(Debug)] pub struct Scout { @@ -282,6 +287,7 @@ impl Scout { /// scout.stop(); /// # }) /// ``` + // tags{scout.stop} pub fn stop(self) { self.scout.stop() } From a5eb563bfccddc71c3b67d13652fda084fd2e64d Mon Sep 17 00:00:00 2001 From: Michael Ilyin Date: Mon, 5 Feb 2024 16:57:19 +0100 Subject: [PATCH 4/5] more tags --- zenoh/src/selector.rs | 37 +++++++++++++++++++++++++++++++++++++ zenoh/src/session.rs | 9 +++++++++ zenoh/src/subscriber.rs | 32 +++++++++++++++++++++----------- zenoh/src/value.rs | 4 ++++ 4 files changed, 71 insertions(+), 11 deletions(-) diff --git a/zenoh/src/selector.rs b/zenoh/src/selector.rs index 2a9a38c02c..dc63b2ac9c 100644 --- a/zenoh/src/selector.rs +++ b/zenoh/src/selector.rs @@ -61,6 +61,7 @@ use std::{ /// this parameter must be readable by the [Zenoh Time DSL](zenoh_util::time_range::TimeRange) for the value to be considered valid. /// - **`[unstable]`** `_anyke`: used in queries to express interest in replies coming from any key expression. By default, only replies /// whose key expression match query's key expression are accepted. `_anyke` disables the query-reply key expression matching check. +// tags{selector} #[non_exhaustive] #[derive(Clone, PartialEq, Eq)] pub struct Selector<'a> { @@ -70,13 +71,16 @@ pub struct Selector<'a> { pub(crate) parameters: Cow<'a, str>, } +// tags{selector.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.set} 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.set} pub fn set_parameters(&mut self, selector: impl Into>) { self.parameters = selector.into(); } + // ignore_tagging pub fn borrowing_clone(&'a self) -> Self { Selector { key_expr: self.key_expr.clone(), parameters: self.parameters.as_ref().into(), } } + // ignore_tagging 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`"] + // ignore_tagging pub fn to_owned(&self) -> Selector<'static> { self.borrowing_clone().into_owned() } /// Returns this selectors components as a tuple. + // tags{selector.parameters.get} pub fn split(self) -> (KeyExpr<'a>, Cow<'a, str>) { (self.key_expr, self.parameters) } /// Sets the `parameters` part of this `Selector`. #[inline(always)] + // tags{selector.parameters.set} 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.timerange.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.timerange.remove} pub fn remove_time_range(&mut self) { let selector = self.parameters_mut(); @@ -281,10 +297,13 @@ fn selector_accessors() { assert_eq!(selector.to_string(), without_any + "&other"); } } +// tags{selector.parameter} pub trait Parameter: Sized { type Name: AsRef + Sized; type Value: AsRef + Sized; + // tags{selector.parameter.name.get} fn name(&self) -> &Self::Name; + // tags{selector.parameter.value.get} fn value(&self) -> &Self::Value; fn split(self) -> (Self::Name, Self::Value); fn extract_name(self) -> Self::Name { @@ -321,6 +340,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 +349,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 +374,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 +405,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.bools} fn get_bools(&'a self, names: [&str; N]) -> ZResult<[bool; N]> where ::Item: Parameter, @@ -396,6 +419,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.timerange.get} fn time_range(&'a self) -> ZResult> where ::Item: Parameter, @@ -406,12 +430,14 @@ pub trait Parameters<'a> { }) } } +// tags{selector.parameters.get} impl<'a> Parameters<'a> for Selector<'a> { type Decoder = >::Decoder; fn decode(&'a self) -> Self::Decoder { self.parameters().decode() } } +// tags{selector.parameters.create.from_str} impl<'a> Parameters<'a> for str { type Decoder = form_urlencoded::Parse<'a>; fn decode(&'a self) -> Self::Decoder { @@ -419,6 +445,7 @@ impl<'a> Parameters<'a> for str { } } +// tags{selector.parameters.create.from_hashmap} impl<'a, K: Borrow + Hash + Eq + 'a, V: Borrow + 'a> Parameters<'a> for HashMap { type Decoder = std::collections::hash_map::Iter<'a, K, V>; fn decode(&'a self) -> Self::Decoder { @@ -458,6 +485,7 @@ impl<'a> From<&Selector<'a>> for Selector<'a> { } } +// tags{selector.create.from_str} impl TryFrom for Selector<'_> { type Error = zenoh_result::Error; fn try_from(mut s: String) -> Result { @@ -472,6 +500,7 @@ impl TryFrom for Selector<'_> { } } +// tags{selector.create.from_str} impl<'a> TryFrom<&'a str> for Selector<'a> { type Error = zenoh_result::Error; fn try_from(s: &'a str) -> Result { @@ -484,6 +513,7 @@ impl<'a> TryFrom<&'a str> for Selector<'a> { } } } +// tags{selector.create.from_str} impl FromStr for Selector<'static> { type Err = zenoh_result::Error; fn from_str(s: &str) -> Result { @@ -491,6 +521,7 @@ impl FromStr for Selector<'static> { } } +// tags{selector.create.from_str} impl<'a> TryFrom<&'a String> for Selector<'a> { type Error = zenoh_result::Error; fn try_from(s: &'a String) -> Result { @@ -498,6 +529,7 @@ impl<'a> TryFrom<&'a String> for Selector<'a> { } } +// tags{selector.create.from_query} impl<'a> From<&'a Query> for Selector<'a> { fn from(q: &'a Query) -> Self { Selector { @@ -507,6 +539,7 @@ impl<'a> From<&'a Query> for Selector<'a> { } } +// tags{selector.create.from_keyexpr} impl<'a> From<&KeyExpr<'a>> for Selector<'a> { fn from(key_selector: &KeyExpr<'a>) -> Self { Self { @@ -516,6 +549,7 @@ impl<'a> From<&KeyExpr<'a>> for Selector<'a> { } } +// tags{selector.create.from_keyexpr} impl<'a> From<&'a keyexpr> for Selector<'a> { fn from(key_selector: &'a keyexpr) -> Self { Self { @@ -525,6 +559,7 @@ impl<'a> From<&'a keyexpr> for Selector<'a> { } } +// tags{selector.create.from_keyexpr} impl<'a> From<&'a OwnedKeyExpr> for Selector<'a> { fn from(key_selector: &'a OwnedKeyExpr) -> Self { Self { @@ -534,6 +569,7 @@ impl<'a> From<&'a OwnedKeyExpr> for Selector<'a> { } } +// tags{selector.create.from_keyexpr} impl From for Selector<'static> { fn from(key_selector: OwnedKeyExpr) -> Self { Self { @@ -543,6 +579,7 @@ impl From for Selector<'static> { } } +// tags{selector.create.from_keyexpr} impl<'a> From> for Selector<'a> { fn from(key_selector: KeyExpr<'a>) -> Self { Self { diff --git a/zenoh/src/session.rs b/zenoh/src/session.rs index bdc928fd49..fcb60518e4 100644 --- a/zenoh/src/session.rs +++ b/zenoh/src/session.rs @@ -278,6 +278,8 @@ impl Resource { } } + +// ignore_tagging #[derive(Clone)] pub enum SessionRef<'a> { Borrow(&'a Session), @@ -305,6 +307,7 @@ impl fmt::Debug for SessionRef<'_> { } /// A trait implemented by types that can be undeclared. +// ignore_tagging pub trait Undeclarable> where O: Resolve + Send, @@ -324,6 +327,7 @@ where /// A zenoh session. /// +// tags{session} pub struct Session { pub(crate) runtime: Runtime, pub(crate) state: Arc>, @@ -2578,6 +2582,7 @@ impl fmt::Debug for Session { /// }).await; /// # }) /// ``` +// tags{session} pub trait SessionDeclarations { /// Create a [`Subscriber`](crate::subscriber::Subscriber) for the given key expression. /// @@ -2602,6 +2607,7 @@ pub trait SessionDeclarations { /// }).await; /// # }) /// ``` + // tags{session.declare_subscriber} fn declare_subscriber<'a, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, @@ -2637,6 +2643,7 @@ pub trait SessionDeclarations { /// }).await; /// # }) /// ``` + // tags{session.declare_queryable} fn declare_queryable<'a, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, @@ -2664,6 +2671,7 @@ pub trait SessionDeclarations { /// publisher.put("value").res().await.unwrap(); /// # }) /// ``` + // tags{session.declare_publisher} fn declare_publisher<'a, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, @@ -2688,6 +2696,7 @@ pub trait SessionDeclarations { /// .unwrap(); /// # }) /// ``` + // tags{liveliness.create} #[zenoh_macros::unstable] fn liveliness(&self) -> Liveliness<'static>; } diff --git a/zenoh/src/subscriber.rs b/zenoh/src/subscriber.rs index 3803ae5cf2..68981a3a62 100644 --- a/zenoh/src/subscriber.rs +++ b/zenoh/src/subscriber.rs @@ -130,6 +130,7 @@ impl<'a> PullSubscriberInner<'a> { /// subscriber.pull(); /// # }) /// ``` + // tags{subscriber.pull} #[inline] pub fn pull(&self) -> impl Resolve> + '_ { self.inner.session.pull(&self.inner.state.key_expr) @@ -157,6 +158,7 @@ impl<'a> PullSubscriberInner<'a> { /// subscriber.undeclare().res().await.unwrap(); /// # }) /// ``` + // tags{subscriber.undeclare} #[inline] pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self.inner, ()) @@ -213,6 +215,7 @@ impl<'a> Undeclarable<(), SubscriberUndeclaration<'a>> for SubscriberInner<'a> { /// subscriber.undeclare().res().await.unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct SubscriberUndeclaration<'a> { subscriber: SubscriberInner<'a>, @@ -248,6 +251,7 @@ impl Drop for SubscriberInner<'_> { } /// The mode for pull subscribers. +// tags{subscriber.options.pull_mode} #[non_exhaustive] #[derive(Debug, Clone, Copy)] pub struct PullMode; @@ -265,6 +269,7 @@ impl From for Mode { } /// The mode for push subscribers. +// tags{subscriber.options.push_mode} #[non_exhaustive] #[derive(Debug, Clone, Copy)] pub struct PushMode; @@ -298,6 +303,7 @@ impl From for Mode { /// .unwrap(); /// # }) /// ``` +// ignore_tagging #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] #[derive(Debug)] pub struct SubscriberBuilder<'a, 'b, Mode, Handler> { @@ -349,7 +355,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{session.declare_subscriber.cb} + // tags{subscriber.callback} #[inline] pub fn callback(self, callback: Callback) -> SubscriberBuilder<'a, 'b, Mode, Callback> where @@ -393,7 +399,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{session.declare_subscriber.cb.locked} + // tags{subscriber.callback} #[inline] pub fn callback_mut( self, @@ -424,7 +430,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { /// } /// # }) /// ``` - // tags{session.declare_subscriber.cb.generic} + // tags{subscriber.pipe} #[inline] pub fn with(self, handler: Handler) -> SubscriberBuilder<'a, 'b, Mode, Handler> where @@ -450,7 +456,7 @@ impl<'a, 'b, Mode> SubscriberBuilder<'a, 'b, Mode, DefaultHandler> { } impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Change the subscription reliability. - // tags{session.declare_subscriber.options.reliability} + // tags{subscriber.options.reliability} #[inline] pub fn reliability(mut self, reliability: Reliability) -> Self { self.reliability = reliability; @@ -458,6 +464,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { } /// Change the subscription reliability to `Reliable`. + // tags{subscriber.options.reliability} #[inline] pub fn reliable(mut self) -> Self { self.reliability = Reliability::Reliable; @@ -465,6 +472,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { } /// Change the subscription reliability to `BestEffort`. + // tags{subscriber.options.reliability} #[inline] pub fn best_effort(mut self) -> Self { self.reliability = Reliability::BestEffort; @@ -473,7 +481,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { /// Restrict the matching publications that will be receive by this [`Subscriber`] /// to the ones that have the given [`Locality`](crate::prelude::Locality). - // tags{session.declare_subscriber.options.locality} + // tags{subscriber.options.locality} #[zenoh_macros::unstable] #[inline] pub fn allowed_origin(mut self, origin: Locality) -> Self { @@ -482,7 +490,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { } /// Change the subscription mode to Pull. - // tags{session.declare_subscriber.options.pull} + // tags{subscriber.options.pull_mode} #[inline] pub fn pull_mode(self) -> SubscriberBuilder<'a, 'b, PullMode, Handler> { let SubscriberBuilder { @@ -504,7 +512,7 @@ impl<'a, 'b, Mode, Handler> SubscriberBuilder<'a, 'b, Mode, Handler> { } /// Change the subscription mode to Push. - // tags{session.declare_subscriber.options.push} + // tags{subscriber.options.push_mode} #[inline] pub fn push_mode(self) -> SubscriberBuilder<'a, 'b, PushMode, Handler> { let SubscriberBuilder { @@ -658,6 +666,7 @@ where /// } /// # }) /// ``` +// tags{subscriber} #[non_exhaustive] #[derive(Debug)] pub struct Subscriber<'a, Receiver> { @@ -693,6 +702,7 @@ pub struct Subscriber<'a, Receiver> { /// subscriber.pull(); /// # }) /// ``` +// tags{pull_subscriber} #[non_exhaustive] pub struct PullSubscriber<'a, Receiver> { pub(crate) subscriber: PullSubscriberInner<'a>, @@ -732,7 +742,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { /// subscriber.pull(); /// # }) /// ``` - // tags{session.declare_subscriber.pull} + // tags{pull_subscriber.pull} #[inline] pub fn pull(&self) -> impl Resolve> + '_ { self.subscriber.pull() @@ -757,7 +767,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { /// subscriber.undeclare().res().await.unwrap(); /// # }) /// ``` - // tags{session.declare_subscriber.pull.undeclare} + // tags{pull_subscriber.undeclare} #[inline] pub fn undeclare(self) -> impl Resolve> + 'a { self.subscriber.undeclare() @@ -766,7 +776,7 @@ impl<'a, Receiver> PullSubscriber<'a, Receiver> { impl<'a, Receiver> Subscriber<'a, Receiver> { /// Returns the [`KeyExpr`] this Subscriber subscribes to. - // tags{session.declare_subscriber.push.key_expr} + // tags{subscriber.key_expr.get} pub fn key_expr(&self) -> &KeyExpr<'static> { &self.subscriber.state.key_expr } @@ -789,7 +799,7 @@ impl<'a, Receiver> Subscriber<'a, Receiver> { /// subscriber.undeclare().res().await.unwrap(); /// # }) /// ``` - // tags{session.declare_subscriber.push.undeclare} + // tags{subscriber.undeclare} #[inline] pub fn undeclare(self) -> SubscriberUndeclaration<'a> { self.subscriber.undeclare() diff --git a/zenoh/src/value.rs b/zenoh/src/value.rs index 849cfd57d5..865e66cf87 100644 --- a/zenoh/src/value.rs +++ b/zenoh/src/value.rs @@ -29,6 +29,7 @@ use crate::prelude::{Encoding, KnownEncoding, Sample, SplitBuffer}; use zenoh_shm::SharedMemoryBuf; /// A zenoh Value. +// tags{value} #[non_exhaustive] #[derive(Clone)] pub struct Value { @@ -40,6 +41,7 @@ pub struct Value { impl Value { /// Creates a new zenoh Value. + // tags{value.create.from_buffer} pub fn new(payload: ZBuf) -> Self { Value { payload, @@ -48,6 +50,7 @@ impl Value { } /// Creates an empty Value. + // tags{value.create.empty} pub fn empty() -> Self { Value { payload: ZBuf::empty(), @@ -56,6 +59,7 @@ impl Value { } /// Sets the encoding of this zenoh Value. + // tags{value.encoding.set} #[inline(always)] pub fn encoding(mut self, encoding: Encoding) -> Self { self.encoding = encoding; From efb4a452e388bed92eb4e63846e23d85cf0265e6 Mon Sep 17 00:00:00 2001 From: Michael Ilyin Date: Tue, 6 Feb 2024 18:32:59 +0100 Subject: [PATCH 5/5] more tags --- commons/zenoh-protocol/src/core/mod.rs | 7 +-- zenoh/src/info.rs | 6 +-- zenoh/src/key_expr.rs | 12 +++--- zenoh/src/lib.rs | 6 +-- zenoh/src/liveliness.rs | 14 +++--- zenoh/src/publication.rs | 59 +++++++++++++------------- zenoh/src/query.rs | 32 +++++++------- zenoh/src/queryable.rs | 30 ++++++------- zenoh/src/sample.rs | 23 +++++----- zenoh/src/session.rs | 21 ++++----- 10 files changed, 109 insertions(+), 101 deletions(-) diff --git a/commons/zenoh-protocol/src/core/mod.rs b/commons/zenoh-protocol/src/core/mod.rs index c7aac86703..bff70b3d6e 100644 --- a/commons/zenoh-protocol/src/core/mod.rs +++ b/commons/zenoh-protocol/src/core/mod.rs @@ -61,7 +61,7 @@ pub struct Property { } /// The kind of a `Sample`. -// tags{sample.kind} +// tags{publisher.write.kind} #[repr(u8)] #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] pub enum SampleKind { @@ -93,6 +93,7 @@ impl TryFrom for SampleKind { } /// The global unique id of a zenoh peer. +// tags{zenoh_id} #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[repr(transparent)] pub struct ZenohId(uhlc::ID); @@ -347,7 +348,7 @@ impl TryFrom for Priority { } /// The reliability request of a subscriber. -// tags{options.reliability} +// tags{enum.reliability} #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] pub enum Reliability { @@ -425,7 +426,7 @@ pub enum ConsolidationMode { } /// The `zenoh::queryable::Queryable`s that should be target of a `zenoh::Session::get()`. -// tags{session.query.target} +// tags{enum.query.target} #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] pub enum QueryTarget { #[default] diff --git a/zenoh/src/info.rs b/zenoh/src/info.rs index 2220f2a214..107880e91a 100644 --- a/zenoh/src/info.rs +++ b/zenoh/src/info.rs @@ -182,7 +182,7 @@ impl SessionInfo<'_> { /// let zid = session.info().zid().res().await; /// # }) /// ``` - // tags{session.zid} + // tags{session.zid.get} pub fn zid(&self) -> ZidBuilder<'_> { ZidBuilder { session: self.session.clone(), @@ -202,7 +202,7 @@ impl SessionInfo<'_> { /// while let Some(router_zid) = routers_zid.next() {} /// # }) /// ``` - // tags{session.info.routers_zid} + // tags{session.routers.get} pub fn routers_zid(&self) -> RoutersZidBuilder<'_> { RoutersZidBuilder { session: self.session.clone(), @@ -221,7 +221,7 @@ impl SessionInfo<'_> { /// while let Some(peer_zid) = peers_zid.next() {} /// # }) /// ``` - // tags{session.info.peers_zid} + // tags{session.peers.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 2c42024a5b..7f7c7f8880 100644 --- a/zenoh/src/key_expr.rs +++ b/zenoh/src/key_expr.rs @@ -77,7 +77,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.from_unchecked} + // tags{keyexpr.create.from_string_unchecked} pub unsafe fn from_string_unchecked(s: String) -> Self { Self(KeyExprInner::Owned(OwnedKeyExpr::from_string_unchecked(s))) } @@ -86,7 +86,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.from_unchecked} + // 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), @@ -100,7 +100,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.new} + // tags{keyexpr.create} pub fn new(t: T) -> Result where Self: TryFrom, @@ -163,7 +163,7 @@ 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.from_unchecked} + // tags{keyexpr.create.from_string_unchecked} pub unsafe fn from_str_unchecked(s: &'a str) -> Self { keyexpr::from_str_unchecked(s).into() } @@ -285,7 +285,7 @@ impl<'a> KeyExpr<'a> { } } - // tags{keyexpr.with_parameters} + // tags{selector.create.from_keyexpr} pub fn with_parameters(self, selector: &'a str) -> Selector<'a> { Selector { key_expr: self, @@ -293,7 +293,7 @@ impl<'a> KeyExpr<'a> { } } - // tags{keyexpr.with_parameters} + // tags{selector.create.from_keyexpr} pub fn with_owned_parameters(self, selector: String) -> Selector<'a> { Selector { key_expr: self, diff --git a/zenoh/src/lib.rs b/zenoh/src/lib.rs index e34ff4d71d..e6b7938da1 100644 --- a/zenoh/src/lib.rs +++ b/zenoh/src/lib.rs @@ -161,7 +161,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{time.new_reception_timestamp} + // tags{timestamp.create} pub fn new_reception_timestamp() -> Timestamp { use std::time::{SystemTime, UNIX_EPOCH}; @@ -178,7 +178,7 @@ pub mod properties { /// Convert a set of [`Properties`] into a [`Value`]. /// For instance, Properties: `[("k1", "v1"), ("k2, v2")]` /// is converted into Json: `{ "k1": "v1", "k2": "v2" }` - // tags{properties.properties_to_json_value} + // tags{value.create.from_properties} pub fn properties_to_json_value(props: &Properties) -> Value { let json_map = props .iter() @@ -261,7 +261,7 @@ where /// let session = zenoh::open(config).res().await.unwrap(); /// # }) /// ``` -// tags{session.open} +// tags{session.create} pub fn open(config: TryIntoConfig) -> OpenBuilder where TryIntoConfig: std::convert::TryInto + Send + 'static, diff --git a/zenoh/src/liveliness.rs b/zenoh/src/liveliness.rs index 3185db1866..74fcf52722 100644 --- a/zenoh/src/liveliness.rs +++ b/zenoh/src/liveliness.rs @@ -105,7 +105,7 @@ impl<'a> Liveliness<'a> { /// # }) /// ``` #[zenoh_macros::unstable] - // tags{liveliness.declare_token} + // tags{liveliness.token.create} pub fn declare_token<'b, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, @@ -141,7 +141,7 @@ impl<'a> Liveliness<'a> { /// } /// # }) /// ``` - // tags{liveliness.declare_subscriber} + // tags{liveliness.subscriber.create} #[zenoh_macros::unstable] pub fn declare_subscriber<'b, TryIntoKeyExpr>( &self, @@ -178,7 +178,7 @@ impl<'a> Liveliness<'a> { /// } /// # }) /// ``` - // tags{liveliness.get} + // tags{liveliness.query_token} #[zenoh_macros::unstable] pub fn get<'b: 'a, TryIntoKeyExpr>( &'a self, @@ -640,7 +640,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{liveiness.get.callback} + // tags{liveliness.query_token.callback} #[inline] pub fn callback(self, callback: Callback) -> LivelinessGetBuilder<'a, 'b, Callback> where @@ -681,7 +681,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{liveiness.get.callback} + // tags{liveliness.query_token.callback} #[inline] pub fn callback_mut( self, @@ -713,7 +713,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { /// } /// # }) /// ``` - // tags{liveiness.get.pipe} + // tags{liveliness.query_token.pipe} #[inline] pub fn with(self, handler: Handler) -> LivelinessGetBuilder<'a, 'b, Handler> where @@ -736,7 +736,7 @@ impl<'a, 'b> LivelinessGetBuilder<'a, 'b, DefaultHandler> { impl<'a, 'b, Handler> LivelinessGetBuilder<'a, 'b, Handler> { /// Set query timeout. - // tags{liveiness.get.timeout} + // tags{liveliness.query_token.timeout} #[inline] pub fn timeout(mut self, timeout: Duration) -> Self { self.timeout = timeout; diff --git a/zenoh/src/publication.rs b/zenoh/src/publication.rs index b2503999f9..e175dd7622 100644 --- a/zenoh/src/publication.rs +++ b/zenoh/src/publication.rs @@ -87,7 +87,7 @@ pub struct PutBuilder<'a, 'b> { impl PutBuilder<'_, '_> { /// Change the encoding of the written data. - // tags{session.put.encoding} + // tags{session.put.encoding.set} #[inline] pub fn encoding(mut self, encoding: IntoEncoding) -> Self where @@ -97,7 +97,7 @@ impl PutBuilder<'_, '_> { self } /// Change the `congestion_control` to apply when routing the data. - // tags{session.put.congestion_control} + // tags{session.put.congestion_control.set} #[inline] pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.publisher = self.publisher.congestion_control(congestion_control); @@ -105,7 +105,7 @@ impl PutBuilder<'_, '_> { } /// Change the priority of the written data. - // tags{session.put.priority} + // tags{session.put.priority.set} #[inline] pub fn priority(mut self, priority: Priority) -> Self { self.publisher = self.publisher.priority(priority); @@ -114,7 +114,7 @@ impl PutBuilder<'_, '_> { /// Restrict the matching subscribers that will receive the published data /// to the ones that have the given [`Locality`](crate::prelude::Locality). - // tags{session.put.allowed_destination} + // tags{session.put.allowed_destination.set} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -122,14 +122,14 @@ impl PutBuilder<'_, '_> { self } - // tags{session.put.kind} + // tags{session.put.kind.set} pub fn kind(mut self, kind: SampleKind) -> Self { self.kind = kind; self } #[zenoh_macros::unstable] - // tags{session.put.attachment} + // tags{session.put.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self @@ -243,7 +243,7 @@ impl std::fmt::Debug for PublisherRef<'_> { /// subscriber.stream().map(Ok).forward(publisher).await.unwrap(); /// # }) /// ``` -// tags{session.publisher} +// tags{publisher} #[derive(Debug, Clone)] pub struct Publisher<'a> { pub(crate) session: SessionRef<'a>, @@ -254,13 +254,13 @@ pub struct Publisher<'a> { } impl<'a> Publisher<'a> { - // tags{session.publisher.key_expr} + // 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. - // tags{session.publisher.congestion_control} + // tags{publisher.congestion_control.set} #[inline] pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.congestion_control = congestion_control; @@ -268,7 +268,7 @@ impl<'a> Publisher<'a> { } /// Change the priority of the written data. - // tags{session.publisher.priority} + // tags{publisher.priority.set} #[inline] pub fn priority(mut self, priority: Priority) -> Self { self.priority = priority; @@ -277,7 +277,7 @@ impl<'a> Publisher<'a> { /// Restrict the matching subscribers that will receive the published data /// to the ones that have the given [`Locality`](crate::prelude::Locality). - // tags{session.publisher.allowed_destination} + // tags{publisher.allowed_destination.set} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -343,7 +343,8 @@ impl<'a> Publisher<'a> { /// publisher.write(SampleKind::Put, "value").res().await.unwrap(); /// # }) /// ``` - // tags{session.publisher.write} + // tags{publisher.write.kind} + // tags{publisher.write.value} pub fn write(&self, kind: SampleKind, value: IntoValue) -> Publication where IntoValue: Into, @@ -363,7 +364,7 @@ impl<'a> Publisher<'a> { /// publisher.put("value").res().await.unwrap(); /// # }) /// ``` - // tags{session.publisher.put} + // tags{publisher.put} #[inline] pub fn put(&self, value: IntoValue) -> Publication where @@ -384,7 +385,7 @@ impl<'a> Publisher<'a> { /// publisher.delete().res().await.unwrap(); /// # }) /// ``` - // tags{session.publisher.delete} + // tags{publisher.delete} pub fn delete(&self) -> Publication { self._write(SampleKind::Delete, Value::empty()) } @@ -409,7 +410,7 @@ impl<'a> Publisher<'a> { /// .matching_subscribers(); /// # }) /// ``` - // tags{session.publisher.matching_status} + // tags{publisher.matching_subscribers.get} #[zenoh_macros::unstable] pub fn matching_status(&self) -> impl Resolve> + '_ { zenoh_core::ResolveFuture::new(async move { @@ -440,7 +441,7 @@ impl<'a> Publisher<'a> { /// } /// # }) /// ``` - // tags{session.publisher.matching_listener} + // tags{publisher.matching_listener.create} #[zenoh_macros::unstable] pub fn matching_listener(&self) -> MatchingListenerBuilder<'_, DefaultHandler> { MatchingListenerBuilder { @@ -461,7 +462,7 @@ impl<'a> Publisher<'a> { /// publisher.undeclare().res().await.unwrap(); /// # }) /// ``` - // tags{session.publisher.undeclare} + // tags{publisher.undeclare} pub fn undeclare(self) -> impl Resolve> + 'a { Undeclarable::undeclare_inner(self, ()) } @@ -615,7 +616,7 @@ impl Drop for Publisher<'_> { /// A [`Resolvable`] returned by [`Publisher::put()`](Publisher::put), /// [`Publisher::delete()`](Publisher::delete) and [`Publisher::write()`](Publisher::write). -// ignore_tagging +// tags{} #[must_use = "Resolvables do nothing unless you resolve them using the `res` method from either `SyncResolve` or `AsyncResolve`"] pub struct Publication<'a> { publisher: &'a Publisher<'a>, @@ -626,7 +627,7 @@ pub struct Publication<'a> { } impl<'a> Publication<'a> { - // tags{session.publisher.put.attachment} + // tags{publisher.write.attachment} #[zenoh_macros::unstable] pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); @@ -730,7 +731,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. - // tags{session.publisher.congestion_control} + // tags{publisher.congestion_control.set} #[inline] pub fn congestion_control(mut self, congestion_control: CongestionControl) -> Self { self.congestion_control = congestion_control; @@ -738,7 +739,7 @@ impl<'a, 'b> PublisherBuilder<'a, 'b> { } /// Change the priority of the written data. - // tags{session.publisher.priority} + // tags{publisher.priority.set} #[inline] pub fn priority(mut self, priority: Priority) -> Self { self.priority = priority; @@ -747,7 +748,7 @@ impl<'a, 'b> PublisherBuilder<'a, 'b> { /// Restrict the matching subscribers that will receive the published data /// to the ones that have the given [`Locality`](crate::prelude::Locality). - // tags{session.publisher.allowed_destination} + // tags{publisher.allowed_destination.set} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -901,7 +902,7 @@ fn resolve_put( } /// The Priority of zenoh messages. -// tags{session.put.priority} +// tags{publisher.priority} #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] #[repr(u8)] pub enum Priority { @@ -917,13 +918,13 @@ pub enum Priority { impl Priority { /// The lowest Priority - // tags{session.put.priority.min} + // tags{publisher.priority.min} pub const MIN: Self = Self::Background; /// The highest Priority - // tags{session.put.priority.max} + // tags{publisher.priority.max} pub const MAX: Self = Self::RealTime; /// The number of available priorities - // tags{session.put.priority.num} + // tags{publisher.priority.num} pub const NUM: usize = 1 + Self::MIN as usize - Self::MAX as usize; } @@ -1009,7 +1010,7 @@ impl MatchingStatus { /// .matching_subscribers(); /// # }) /// ``` - /// tags{session.publisher.matching_status.matching_subscribers^} + // tags{} pub fn matching_subscribers(&self) -> bool { self.matching } @@ -1244,7 +1245,7 @@ impl<'a> Undeclarable<(), MatchingListenerUndeclaration<'a>> for MatchingListene /// } /// # }) /// ``` -// tags{session.publisher.matching_listener} +// tags{publisher.matching_listener} #[zenoh_macros::unstable] pub struct MatchingListener<'a, Receiver> { pub(crate) listener: MatchingListenerInner<'a>, @@ -1269,7 +1270,7 @@ impl<'a, Receiver> MatchingListener<'a, Receiver> { /// matching_listener.undeclare().res().await.unwrap(); /// # }) /// ``` - // tags{session.publisher.matching_listener.undeclare} + // tags{publisher.matching_listener.undeclare} #[inline] pub fn undeclare(self) -> MatchingListenerUndeclaration<'a> { self.listener.undeclare() diff --git a/zenoh/src/query.rs b/zenoh/src/query.rs index bfac886cb4..5d02fc4f57 100644 --- a/zenoh/src/query.rs +++ b/zenoh/src/query.rs @@ -40,7 +40,7 @@ pub enum Mode { } /// The replies consolidation strategy to apply on replies to a [`get`](Session::get). -// tags{session.get.consolidation_mode} +// tags{session.query_reply.consolidation_mode} #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct QueryConsolidation { pub(crate) mode: Mode, @@ -48,7 +48,7 @@ pub struct QueryConsolidation { impl QueryConsolidation { /// Automatic query consolidation strategy selection. - // tags{session.get.consolidation_mode.auto} + // tags{session.query_reply.consolidation_mode.auto} pub const AUTO: Self = Self { mode: Mode::Auto }; pub(crate) const fn from_mode(mode: ConsolidationMode) -> Self { @@ -81,13 +81,15 @@ impl Default for QueryConsolidation { } /// Structs returned by a [`get`](Session::get). -// tags{session.get.reply} +// tags{reply} #[non_exhaustive] #[derive(Clone, Debug)] pub struct Reply { /// The result of this Reply. + // tags{reply.sample} pub sample: Result, /// The id of the zenoh instance that answered this Reply. + // tags{reply.replier_id} pub replier_id: ZenohId, } @@ -155,7 +157,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{session.get.callback} + // tags{session.query_reply.callback} #[inline] pub fn callback(self, callback: Callback) -> GetBuilder<'a, 'b, Callback> where @@ -209,7 +211,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{session.get.callback} + // tags{session.query_reply.callback} #[inline] pub fn callback_mut( self, @@ -240,7 +242,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { /// } /// # }) /// ``` - // tags{session.get.pipe} + // tags{session.query_reply.pipe} #[inline] pub fn with(self, handler: Handler) -> GetBuilder<'a, 'b, Handler> where @@ -276,7 +278,7 @@ impl<'a, 'b> GetBuilder<'a, 'b, DefaultHandler> { } impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Change the target of the query. - // tags{session.get.target} + // tags{session.query_reply.target.set} #[inline] pub fn target(mut self, target: QueryTarget) -> Self { self.target = target; @@ -284,7 +286,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } /// Change the consolidation mode of the query. - // tags{session.get.consolidation_mode} + // tags{session.query_reply.consolidation_mode.set} #[inline] pub fn consolidation>(mut self, consolidation: QC) -> Self { self.consolidation = consolidation.into(); @@ -293,7 +295,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { /// Restrict the matching queryables that will receive the query /// to the ones that have the given [`Locality`](crate::prelude::Locality). - // tags{session.get.allowed_destination} + // tags{session.query_reply.allowed_destination.set} #[zenoh_macros::unstable] #[inline] pub fn allowed_destination(mut self, destination: Locality) -> Self { @@ -302,7 +304,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } /// Set query timeout. - // tags{session.get.timeout} + // tags{session.query_reply.timeout.set} #[inline] pub fn timeout(mut self, timeout: Duration) -> Self { self.timeout = timeout; @@ -310,7 +312,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } /// Set query value. - // tags{session.get.value} + // tags{session.query_reply.value.set} #[inline] pub fn with_value(mut self, value: IntoValue) -> Self where @@ -321,7 +323,7 @@ impl<'a, 'b, Handler> GetBuilder<'a, 'b, Handler> { } #[zenoh_macros::unstable] - // tags{session.get.attachment} + // tags{session.query_reply.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self @@ -332,7 +334,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. - // tags{session.get.accept_replies} + // tags{session.query_reply.accept_replies.set} #[zenoh_macros::unstable] pub fn accept_replies(self, accept: ReplyKeyExpr) -> Self { let Self { @@ -364,12 +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{session.get.reply_key_expr_any_sel_param} +// tags{session.query_reply.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{session.get.accept_replies} +// tags{session.query_reply.accept_replies} pub enum ReplyKeyExpr { Any, MatchingQuery, diff --git a/zenoh/src/queryable.rs b/zenoh/src/queryable.rs index b9960df82d..3971f749ba 100644 --- a/zenoh/src/queryable.rs +++ b/zenoh/src/queryable.rs @@ -63,7 +63,7 @@ impl Drop for QueryInner { } /// Structs received by a [`Queryable`]. -// tags{session.queryable} +// tags{query} #[derive(Clone)] pub struct Query { pub(crate) inner: Arc, @@ -71,7 +71,7 @@ pub struct Query { impl Query { /// The full [`Selector`] of this Query. - // tags{session.queryable.selector} + // tags{query.selector.get} #[inline(always)] pub fn selector(&self) -> Selector<'_> { Selector { @@ -81,27 +81,27 @@ impl Query { } /// The key selector part of this Query. - // tags{session.queryable.selector.key_expr} + // tags{query.selector.key_expr.get} #[inline(always)] pub fn key_expr(&self) -> &KeyExpr<'static> { &self.inner.key_expr } /// This Query's selector parameters. - // tags{session.queryable.selector.parameters} + // tags{query.selector.parameters.get} #[inline(always)] pub fn parameters(&self) -> &str { &self.inner.parameters } /// This Query's value. - // tags{session.queryable.value} + // tags{query.value.get} #[inline(always)] pub fn value(&self) -> Option<&Value> { self.inner.value.as_ref() } - // tags{session.queryable.attachment} + // tags{query.attachment.get} #[zenoh_macros::unstable] pub fn attachment(&self) -> Option<&Attachment> { self.inner.attachment.as_ref() @@ -112,7 +112,7 @@ impl Query { /// By default, queries only accept replies whose key expression intersects with the query's. /// 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. - // tags{session.queryable.reply} + // tags{query.reply} #[inline(always)] pub fn reply(&self, result: Result) -> ReplyBuilder<'_> { ReplyBuilder { @@ -123,7 +123,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. - // tags{session.queryable.accepts_replies} + // tags{query.accepts_replies.get} #[zenoh_macros::unstable] pub fn accepts_replies(&self) -> ZResult { self._accepts_any_replies().map(|any| { @@ -173,7 +173,7 @@ pub struct ReplyBuilder<'a> { impl<'a> ReplyBuilder<'a> { #[allow(clippy::result_large_err)] #[zenoh_macros::unstable] - // tags{session.queryable.reply.attachment} + // tags{query.reply.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Result { match &mut self.result { Ok(sample) => { @@ -448,7 +448,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{session.queryable.callback} + // tags{queryable.callback} #[inline] pub fn callback(self, callback: Callback) -> QueryableBuilder<'a, 'b, Callback> where @@ -490,7 +490,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// .unwrap(); /// # }) /// ``` - // tags{session.queryable.callback} + // tags{queryable.callback} #[inline] pub fn callback_mut( self, @@ -521,7 +521,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// } /// # }) /// ``` - // tags{session.queryable.pipe} + // tags{queryable.pipe} #[inline] pub fn with(self, handler: Handler) -> QueryableBuilder<'a, 'b, Handler> where @@ -545,7 +545,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { /// Restrict the matching queries that will be receive by this [`Queryable`] /// to the ones that have the given [`Locality`](crate::prelude::Locality). - // tags{session.queryable.allowed_origin} + // tags{queryable.allowed_origin} #[inline] #[zenoh_macros::unstable] pub fn allowed_origin(mut self, origin: Locality) -> Self { @@ -555,7 +555,7 @@ impl<'a, 'b> QueryableBuilder<'a, 'b, DefaultHandler> { } impl<'a, 'b, Handler> QueryableBuilder<'a, 'b, Handler> { /// Change queryable completeness. - // tags{session.queryable.complete} + // tags{queryable.complete} #[inline] pub fn complete(mut self, complete: bool) -> Self { self.complete = complete; @@ -603,7 +603,7 @@ pub struct Queryable<'a, Receiver> { impl<'a, Receiver> Queryable<'a, Receiver> { #[inline] - // tags{session.queryable.undeclare} + // 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 456fe93a52..3e9a7fa576 100644 --- a/zenoh/src/sample.rs +++ b/zenoh/src/sample.rs @@ -59,8 +59,10 @@ pub(crate) struct DataInfo { #[derive(Debug, Clone)] pub struct SourceInfo { /// The [`ZenohId`] of the zenoh instance that published the concerned [`Sample`]. + // tags{sample.source_info.source_id} pub source_id: Option, /// The sequence number of the [`Sample`] from the source. + // tags{sample.source_info.source_sn} pub source_sn: Option, } @@ -189,7 +191,7 @@ mod attachment { } #[zenoh_macros::unstable] impl Attachment { - // tags{sample.attachment.new} + // tags{sample.attachment.create} pub fn new() -> Self { Self { inner: ZBuf::empty(), @@ -367,7 +369,7 @@ pub struct Sample { impl Sample { /// Creates a new Sample. - // tags{sample.new} + // tags{sample.create} #[inline] pub fn new(key_expr: IntoKeyExpr, value: IntoValue) -> Self where @@ -386,7 +388,7 @@ impl Sample { } } /// Creates a new Sample. - // tags{sample.from_value} + // tags{sample.create.from_value} #[inline] pub fn try_from( key_expr: TryIntoKeyExpr, @@ -410,7 +412,7 @@ impl Sample { } /// Creates a new Sample with optional data info. - // tags{sample.with_info} + // tags{sample.create.with_info} #[inline] pub(crate) fn with_info( key_expr: KeyExpr<'static>, @@ -447,14 +449,14 @@ impl Sample { } /// Gets the timestamp of this Sample. - // tags{sample.get_timestamp} + // tags{sample.timestamp.get} #[inline] pub fn get_timestamp(&self) -> Option<&Timestamp> { self.timestamp.as_ref() } /// Sets the timestamp of this Sample. - // tags{sample.with_timestamp} + // tags{sample.timestamp.set} #[inline] pub fn with_timestamp(mut self, timestamp: Timestamp) -> Self { self.timestamp = Some(timestamp); @@ -462,7 +464,7 @@ impl Sample { } /// Sets the source info of this Sample. - // tags{sample.with_source_info} + // tags{sample.source_info.set} #[zenoh_macros::unstable] #[inline] pub fn with_source_info(mut self, source_info: SourceInfo) -> Self { @@ -486,20 +488,21 @@ impl Sample { } #[zenoh_macros::unstable] - // tags{sample.get_attachment} + // tags{sample.attachment.get} pub fn attachment(&self) -> Option<&Attachment> { self.attachment.as_ref() } #[zenoh_macros::unstable] - // tags{sample.get_attachment_mut} + // tags{sample.attachment.get} + // tags{sample.attachment.set} pub fn attachment_mut(&mut self) -> &mut Option { &mut self.attachment } #[allow(clippy::result_large_err)] #[zenoh_macros::unstable] - // tags{sample.with_attachment} + // tags{sample.attachment.set} pub fn with_attachment(mut self, attachment: Attachment) -> Self { self.attachment = Some(attachment); self diff --git a/zenoh/src/session.rs b/zenoh/src/session.rs index fcb60518e4..f7a8dc25d9 100644 --- a/zenoh/src/session.rs +++ b/zenoh/src/session.rs @@ -394,7 +394,7 @@ impl Session { /// }).await; /// # }) /// ``` - // tags{session.rc} + // tags{} pub fn into_arc(self) -> Arc { Arc::new(self) } @@ -433,12 +433,12 @@ impl Session { /// 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} + // tags{session.zid.get} pub fn zid(&self) -> ZenohId { self.info().zid().res_sync() } - // tags{session.clock} + // tags{session.clock.get} pub fn hlc(&self) -> Option<&HLC> { self.runtime.hlc() } @@ -506,7 +506,8 @@ impl Session { /// let _ = session.config().insert_json5("connect/endpoints", r#"["tcp/127.0.0.1/7447"]"#); /// # }) /// ``` - // tags{session.config{get, subscribe}} + // tags{session.config.get} + // tags{session.config.subscribe} pub fn config(&self) -> &Notifier { self.runtime.config() } @@ -522,7 +523,7 @@ impl Session { /// let info = session.info(); /// # }) /// ``` - // tags{session.info} + // tags{} pub fn info(&self) -> SessionInfo { SessionInfo { session: SessionRef::Borrow(self), @@ -547,7 +548,7 @@ impl Session { /// } /// # }) /// ``` - // tags{session.declare_subscriber} + // tags{subscriber.create} pub fn declare_subscriber<'a, 'b, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -588,7 +589,7 @@ impl Session { /// } /// # }) /// ``` - // tags{session.declare_queryable} + // tags{queryable.create} pub fn declare_queryable<'a, 'b, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -625,7 +626,7 @@ impl Session { /// publisher.put("value").res().await.unwrap(); /// # }) /// ``` - // tags{session.declare_publisher} + // tags{publisher.create} pub fn declare_publisher<'a, 'b, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, @@ -799,7 +800,7 @@ impl Session { /// } /// # }) /// ``` - // tags{session.get} + // tags{session.query_reply} pub fn get<'a, 'b: 'a, IntoSelector>( &'a self, selector: IntoSelector, @@ -844,7 +845,7 @@ impl Session { /// .unwrap(); /// # }) /// ``` - // tags{liveliness} + // tags{liveliness.create} #[zenoh_macros::unstable] pub fn liveliness(&self) -> Liveliness { Liveliness {