Update documentation for the API changes

Signed-off-by: Michael X. Grey <[email protected]>

Author: mxgrey

examples/minimal_pub_sub/src/minimal_two_nodes.rs

@@ -8,7 +8,7 @@ use anyhow::{Error, Result};
 struct MinimalSubscriber {
     num_messages: AtomicU32,
     node: rclrs::Node,
-    subscription: Mutex<Option<Arc<rclrs::Subscription<std_msgs::msg::String>>>>,
+    subscription: Mutex<Option<rclrs::Subscription<std_msgs::msg::String>>>,
 }
 
 impl MinimalSubscriber {

examples/rust_pubsub/src/simple_publisher.rs

@@ -3,7 +3,7 @@ use std::{sync::Arc, thread, time::Duration};
 use std_msgs::msg::String as StringMsg;
 
 struct SimplePublisher {
-    publisher: Arc<Publisher<StringMsg>>,
+    publisher: Publisher<StringMsg>,
 }
 
 impl SimplePublisher {

examples/rust_pubsub/src/simple_subscriber.rs

@@ -7,7 +7,7 @@ use std::{
 use std_msgs::msg::String as StringMsg;
 
 pub struct SimpleSubscriptionNode {
-    _subscriber: Arc<Subscription<StringMsg>>,
+    _subscriber: Subscription<StringMsg>,
     data: Arc<Mutex<Option<StringMsg>>>,
 }
 

rclrs/src/client.rs

@@ -67,7 +67,7 @@ type RequestId = i64;
 /// The only available way to instantiate clients is via [`Node::create_client`][1], this is to
 /// ensure that [`Node`][2]s can track all the clients that have been created.
 ///
-/// [1]: crate::Node::create_client
+/// [1]: crate::NodeState::create_client
 /// [2]: crate::Node
 pub struct Client<T>
 where

rclrs/src/node.rs

@@ -21,8 +21,9 @@ use rosidl_runtime_rs::Message;
 use crate::{
     rcl_bindings::*, Client, ClientBase, ClientOptions, Clock, ContextHandle, GuardCondition,
     ParameterBuilder, ParameterInterface, ParameterVariant, Parameters, Publisher, PublisherOptions,
-    RclrsError, Service, ServiceBase, ServiceOptions, Subscription, SubscriptionBase, SubscriptionCallback,
-    SubscriptionOptions, TimeSource, ENTITY_LIFECYCLE_MUTEX,
+    PublisherState, RclrsError, Service, ServiceBase, ServiceOptions, ServiceState, Subscription,
+    SubscriptionBase, SubscriptionCallback, SubscriptionOptions, SubscriptionState, TimeSource,
+    ENTITY_LIFECYCLE_MUTEX,
 };
 
 // SAFETY: The functions accessing this type, including drop(), shouldn't care about the thread
@@ -39,7 +40,7 @@ unsafe impl Send for rcl_node_t {}
 /// to exist and be displayed by e.g. `ros2 topic` as long as any one of its primitives is not dropped.
 ///
 /// # Creating
-/// Use [`Executor::create_node`] to create a new node. Pass in [`NodeOptions`] to set all the different
+/// Use [`Executor::create_node`][7] to create a new node. Pass in [`NodeOptions`] to set all the different
 /// options for node creation, or just pass in a string for the node's name if the default options are okay.
 ///
 /// # Naming
@@ -58,27 +59,30 @@ unsafe impl Send for rcl_node_t {}
 /// In that sense, the parameters to the node creation functions are only the _default_ namespace and
 /// name.
 /// See also the [official tutorial][1] on the command line arguments for ROS nodes, and the
-/// [`Node::namespace()`] and [`Node::name()`] functions for examples.
+/// [`Node::namespace()`][3] and [`Node::name()`][4] functions for examples.
 ///
 /// ## Rules for valid names
 /// The rules for valid node names and node namespaces are explained in
-/// [`NodeBuilder::new()`][3] and [`NodeBuilder::namespace()`][4].
+/// [`NodeOptions::new()`][5] and [`NodeOptions::namespace()`][6].
 ///
 /// The `Node` object is really just a shared [`NodeState`], so see the [`NodeState`]
 /// API to see the various operations you can do with a node, such as creating
 /// subscriptions, publishers, services, and clients.
 ///
 /// [1]: https://docs.ros.org/en/rolling/Tutorials/Understanding-ROS2-Nodes.html
 /// [2]: https://docs.ros.org/en/rolling/How-To-Guides/Node-arguments.html
-/// [3]: crate::NodeBuilder::new
-/// [4]: crate::NodeBuilder::namespace
+/// [3]: NodeState::namespace
+/// [4]: NodeState::name
+/// [5]: crate::NodeOptions::new
+/// [6]: crate::NodeOptions::namespace
+/// [7]: crate::Executor::create_node
 pub type Node = Arc<NodeState>;
 
 /// The inner state of a [`Node`].
 ///
 /// This is public so that you can choose to put it inside a [`Weak`] if you
 /// want to be able to refer to a [`Node`] in a non-owning way. It is generally
-/// recommended to manage the [`NodeState`] inside of an [`Arc`], and [`Node`]
+/// recommended to manage the `NodeState` inside of an [`Arc`], and [`Node`]
 /// is provided as convenience alias for that.
 ///
 /// The public API of the [`Node`] type is implemented via `NodeState`.
@@ -187,7 +191,7 @@ impl NodeState {
     /// Returns the fully qualified name of the node.
     ///
     /// The fully qualified name of the node is the node namespace combined with the node name.
-    /// It is subject to the remappings shown in [`Node::name()`] and [`Node::namespace()`].
+    /// It is subject to the remappings shown in [`Node::name()`][1] and [`Node::namespace()`][2].
     ///
     /// # Example
     /// ```
@@ -200,6 +204,9 @@ impl NodeState {
     /// assert_eq!(node.fully_qualified_name(), "/my/namespace/my_node");
     /// # Ok::<(), RclrsError>(())
     /// ```
+    ///
+    /// [1]: NodeState::name
+    /// [2]: NodeState::namespace
     pub fn fully_qualified_name(&self) -> String {
         self.call_string_getter(rcl_node_get_fully_qualified_name)
     }
@@ -246,7 +253,9 @@ impl NodeState {
     /// remain the default service options. Note that clients are generally
     /// expected to use [reliable][2], so it's best not to change the reliability
     /// setting unless you know what you are doing.
+    ///
     /// [1]: crate::Client
+    /// [2]: crate::QoSReliabilityPolicy::Reliable
     // TODO: make client's lifetime depend on node's lifetime
     pub fn create_client<'a, T>(
         &self,
@@ -263,12 +272,12 @@ impl NodeState {
     /// Creates a [`GuardCondition`][1] with no callback.
     ///
     /// A weak pointer to the `GuardCondition` is stored within this node.
-    /// When this node is added to a wait set (e.g. when calling `spin_once`[2]
+    /// When this node is added to a wait set (e.g. when [spinning][2]
     /// with this node as an argument), the guard condition can be used to
     /// interrupt the wait.
     ///
     /// [1]: crate::GuardCondition
-    /// [2]: crate::spin_once
+    /// [2]: crate::Executor::spin
     pub fn create_guard_condition(&self) -> Arc<GuardCondition> {
         let guard_condition = Arc::new(GuardCondition::new_with_context_handle(
             Arc::clone(&self.handle.context_handle),
@@ -282,12 +291,12 @@ impl NodeState {
     /// Creates a [`GuardCondition`][1] with a callback.
     ///
     /// A weak pointer to the `GuardCondition` is stored within this node.
-    /// When this node is added to a wait set (e.g. when calling `spin_once`[2]
+    /// When this node is added to a wait set (e.g. when [spinning][2]
     /// with this node as an argument), the guard condition can be used to
     /// interrupt the wait.
     ///
     /// [1]: crate::GuardCondition
-    /// [2]: crate::spin_once
+    /// [2]: crate::Executor::spin
     pub fn create_guard_condition_with_callback<F>(&mut self, callback: F) -> Arc<GuardCondition>
     where
         F: Fn() + Send + Sync + 'static,
@@ -339,11 +348,11 @@ impl NodeState {
     pub fn create_publisher<'a, T>(
         &self,
         options: impl Into<PublisherOptions<'a>>,
-    ) -> Result<Arc<Publisher<T>>, RclrsError>
+    ) -> Result<Publisher<T>, RclrsError>
     where
         T: Message,
     {
-        let publisher = Arc::new(Publisher::<T>::new(Arc::clone(&self.handle), options)?);
+        let publisher = Arc::new(PublisherState::<T>::new(Arc::clone(&self.handle), options)?);
         Ok(publisher)
     }
 
@@ -396,12 +405,12 @@ impl NodeState {
         &self,
         options: impl Into<ServiceOptions<'a>>,
         callback: F,
-    ) -> Result<Arc<Service<T>>, RclrsError>
+    ) -> Result<Service<T>, RclrsError>
     where
         T: rosidl_runtime_rs::Service,
         F: Fn(&rmw_request_id_t, T::Request) -> T::Response + 'static + Send,
     {
-        let service = Arc::new(Service::<T>::new(
+        let service = Arc::new(ServiceState::<T>::new(
             Arc::clone(&self.handle),
             options,
             callback,
@@ -460,11 +469,11 @@ impl NodeState {
         &self,
         options: impl Into<SubscriptionOptions<'a>>,
         callback: impl SubscriptionCallback<T, Args>,
-    ) -> Result<Arc<Subscription<T>>, RclrsError>
+    ) -> Result<Subscription<T>, RclrsError>
     where
         T: Message,
     {
-        let subscription = Arc::new(Subscription::<T>::new(
+        let subscription = Arc::new(SubscriptionState::<T>::new(
             Arc::clone(&self.handle),
             options,
             callback,

rclrs/src/node/node_options.rs

@@ -9,10 +9,9 @@ use crate::{
     QoSProfile, RclrsError, TimeSource, ToResult, ENTITY_LIFECYCLE_MUTEX, QOS_PROFILE_CLOCK,
 };
 
-/// A builder for creating a [`Node`][1].
+/// A set of options for creating a [`Node`][1].
 ///
 /// The builder pattern allows selectively setting some fields, and leaving all others at their default values.
-/// This struct instance can be created via [`Node::builder()`][2].
 ///
 /// The default values for optional fields are:
 /// - `namespace: "/"`
@@ -43,7 +42,6 @@ use crate::{
 /// ```
 ///
 /// [1]: crate::Node
-/// [2]: crate::Node::builder
 pub struct NodeOptions {
     name: String,
     namespace: String,
@@ -68,7 +66,7 @@ impl NodeOptions {
     /// - Must not be empty and not be longer than `RMW_NODE_NAME_MAX_NAME_LENGTH`
     /// - Must not start with a number
     ///
-    /// Note that node name validation is delayed until [`NodeBuilder::build()`][3].
+    /// Note that node name validation is delayed until [`Executor::create_node`][3].
     ///
     /// # Example
     /// ```
@@ -88,7 +86,7 @@ impl NodeOptions {
     ///
     /// [1]: crate::Node#naming
     /// [2]: https://docs.ros2.org/latest/api/rmw/validate__node__name_8h.html#a5690a285aed9735f89ef11950b6e39e3
-    /// [3]: NodeBuilder::build
+    /// [3]: crate::Executor::create_node
     pub fn new(name: impl ToString) -> NodeOptions {
         NodeOptions {
             name: name.to_string(),
@@ -119,7 +117,7 @@ impl NodeOptions {
     /// - Must not contain two or more `/` characters in a row
     /// - Must not have a `/` character at the end, except if `/` is the full namespace
     ///
-    /// Note that namespace validation is delayed until [`NodeBuilder::build()`][4].
+    /// Note that namespace validation is delayed until [`Executor::create_node`][4].
     ///
     /// # Example
     /// ```
@@ -150,7 +148,7 @@ impl NodeOptions {
     /// [1]: crate::Node#naming
     /// [2]: http://design.ros2.org/articles/topic_and_service_names.html
     /// [3]: https://docs.ros2.org/latest/api/rmw/validate__namespace_8h.html#a043f17d240cf13df01321b19a469ee49
-    /// [4]: NodeBuilder::build
+    /// [4]: crate::Executor::create_node
     pub fn namespace(mut self, namespace: impl ToString) -> Self {
         self.namespace = namespace.to_string();
         self

rclrs/src/node/primitive_options.rs

@@ -39,8 +39,8 @@ pub struct PrimitiveOptions<'a> {
     pub liveliness: Option<QoSLivelinessPolicy>,
     /// Override the default [`QoSProfile::liveliness_lease_duration`] for the primitive.
     pub liveliness_lease: Option<QoSDuration>,
-    /// Override the default [`QoSProfile::avoid_ros_namespace_convention`] for the primitive.
-    pub avoid_ros_namespace_convention: Option<bool>,
+    /// Override the default [`QoSProfile::avoid_ros_namespace_conventions`] for the primitive.
+    pub avoid_ros_namespace_conventions: Option<bool>,
 }
 
 /// Trait to implicitly convert a compatible object into [`PrimitiveOptions`].
@@ -205,7 +205,7 @@ impl<'a> PrimitiveOptions<'a> {
             lifespan: None,
             liveliness: None,
             liveliness_lease: None,
-            avoid_ros_namespace_convention: None,
+            avoid_ros_namespace_conventions: None,
         }
     }
 
@@ -239,7 +239,7 @@ impl<'a> PrimitiveOptions<'a> {
             qos.liveliness_lease = liveliness_lease;
         }
 
-        if let Some(convention) = self.avoid_ros_namespace_convention {
+        if let Some(convention) = self.avoid_ros_namespace_conventions {
             qos.avoid_ros_namespace_conventions = convention;
         }
     }

rclrs/src/parameter.rs

@@ -82,7 +82,9 @@ enum DeclaredValue {
 }
 
 /// Builder used to declare a parameter. Obtain this by calling
-/// [`crate::Node::declare_parameter`].
+/// [`Node::declare_parameter`][1].
+///
+/// [1]: crate::NodeState::declare_parameter
 #[must_use]
 pub struct ParameterBuilder<'a, T: ParameterVariant> {
     name: Arc<str>,

rclrs/src/parameter/service.rs

@@ -17,17 +17,17 @@ use crate::{
 // What is used is the Weak that is stored in the node, and is upgraded when spinning.
 pub struct ParameterService {
     #[allow(dead_code)]
-    describe_parameters_service: Arc<Service<DescribeParameters>>,
+    describe_parameters_service: Service<DescribeParameters>,
     #[allow(dead_code)]
-    get_parameter_types_service: Arc<Service<GetParameterTypes>>,
+    get_parameter_types_service: Service<GetParameterTypes>,
     #[allow(dead_code)]
-    get_parameters_service: Arc<Service<GetParameters>>,
+    get_parameters_service: Service<GetParameters>,
     #[allow(dead_code)]
-    list_parameters_service: Arc<Service<ListParameters>>,
+    list_parameters_service: Service<ListParameters>,
     #[allow(dead_code)]
-    set_parameters_service: Arc<Service<SetParameters>>,
+    set_parameters_service: Service<SetParameters>,
     #[allow(dead_code)]
-    set_parameters_atomically_service: Arc<Service<SetParametersAtomically>>,
+    set_parameters_atomically_service: Service<SetParametersAtomically>,
 }
 
 fn describe_parameters(

rclrs/src/publisher.rs

@@ -45,15 +45,32 @@ impl Drop for PublisherHandle {
 
 /// Struct for sending messages of type `T`.
 ///
+/// Create a publisher using [`Node::create_publisher`][1].
+///
 /// Multiple publishers can be created for the same topic, in different nodes or the same node.
+/// A clone of a `Publisher` will refer to the same publisher instance as the original.
+/// The underlying instance is tied to [`PublisherState`] which implements the [`Publisher`] API.
 ///
 /// The underlying RMW will decide on the concrete delivery mechanism (network stack, shared
 /// memory, or intraprocess).
 ///
-/// Sending messages does not require calling [`spin`][1] on the publisher's node.
+/// Sending messages does not require the node's executor to [spin][2].
+///
+/// [1]: crate::NodeState::create_publisher
+/// [2]: crate::Executor::spin
+pub type Publisher<T> = Arc<PublisherState<T>>;
+
+/// The inner state of a [`Publisher`].
+///
+/// This is public so that you can choose to create a [`Weak`][1] reference to it
+/// if you want to be able to refer to a [`Publisher`] in a non-owning way. It is
+/// generally recommended to manage the `PublisherState` inside of an [`Arc`],
+/// and [`Publisher`] is provided as a convenience alias for that.
+///
+/// The public API of the [`Publisher`] type is implemented via `PublisherState`.
 ///
-/// [1]: crate::spin
-pub struct Publisher<T>
+/// [1]: std::sync::Weak
+pub struct PublisherState<T>
 where
     T: Message,
 {
@@ -66,12 +83,12 @@ where
 
 // SAFETY: The functions accessing this type, including drop(), shouldn't care about the thread
 // they are running in. Therefore, this type can be safely sent to another thread.
-unsafe impl<T> Send for Publisher<T> where T: Message {}
+unsafe impl<T> Send for PublisherState<T> where T: Message {}
 // SAFETY: The type_support_ptr prevents the default Sync impl.
 // rosidl_message_type_support_t is a read-only type without interior mutability.
-unsafe impl<T> Sync for Publisher<T> where T: Message {}
+unsafe impl<T> Sync for PublisherState<T> where T: Message {}
 
-impl<T> Publisher<T>
+impl<T> PublisherState<T>
 where
     T: Message,
 {
@@ -179,7 +196,7 @@ where
     }
 }
 
-impl<T> Publisher<T>
+impl<T> PublisherState<T>
 where
     T: RmwMessage,
 {
@@ -260,7 +277,7 @@ impl<'a, T: IntoPrimitiveOptions<'a>> From<T> for PublisherOptions<'a> {
     }
 }
 
-/// Convenience trait for [`Publisher::publish`].
+/// Convenience trait for [`PublisherState::publish`].
 pub trait MessageCow<'a, T: Message> {
     /// Wrap the owned or borrowed message in a `Cow`.
     fn into_cow(self) -> Cow<'a, T>;