Fix documentation

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

Author: mxgrey

rclrs/src/context.rs

@@ -83,13 +83,13 @@ impl Context {
     /// Creates a new context.
     ///
     /// * `args` - A sequence of strings that resembles command line arguments
-    /// that users can pass into a ROS executable. See [the official tutorial][1]
-    /// to know what these arguments may look like. To simply pass in the arguments
-    /// that the user has provided from the command line, call [`Self::from_env`]
-    /// or [`Self::default_from_env`] instead.
+    ///   that users can pass into a ROS executable. See [the official tutorial][1]
+    ///   to know what these arguments may look like. To simply pass in the arguments
+    ///   that the user has provided from the command line, call [`Self::from_env`]
+    ///   or [`Self::default_from_env`] instead.
     ///
     /// * `options` - Additional options that your application can use to override
-    /// settings that would otherwise be determined by the environment.
+    ///   settings that would otherwise be determined by the environment.
     ///
     /// Creating a context will fail if `args` contains invalid ROS arguments.
     ///

rclrs/src/node.rs

@@ -28,9 +28,13 @@ unsafe impl Send for rcl_node_t {}
 /// Nodes are a core concept in ROS 2. Refer to the official ["Understanding ROS 2 nodes"][1]
 /// tutorial for an introduction.
 ///
-/// Ownership of the node is shared with all [`Publisher`]s and [`Subscription`]s created from it.
-/// That means that even after the node itself is dropped, it will continue to exist and be
-/// displayed by e.g. `ros2 topic` as long as its publishers and subscriptions are not dropped.
+/// Ownership of the node is shared with all the primitives such as [`Publisher`]s and [`Subscription`]s
+/// that are created from it. That means that even after the `Node` itself is dropped, it will continue
+/// 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`][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
 /// A node has a *name* and a *namespace*.
@@ -48,16 +52,19 @@ 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].
 ///
 /// [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]: Node::namespace
+/// [4]: Node::name
+/// [5]: crate::NodeOptions::new
+/// [6]: crate::NodeOptions::namespace
+/// [7]: crate::Executor::create_node
 #[derive(Clone)]
 pub struct Node {
     pub(crate) primitives: Arc<NodePrimitives>,
@@ -213,12 +220,11 @@ impl Node {
     /// 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]
-    /// with this node as an argument), the guard condition can be used to
-    /// interrupt the wait.
+    /// When this node is added to a wait set (e.g. when its executor is [spinning][2]),
+    /// 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),
@@ -232,12 +238,11 @@ impl Node {
     /// 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]
-    /// with this node as an argument), the guard condition can be used to
-    /// interrupt the wait.
+    /// When this node is added to a wait set (e.g. when its executor is [spinning][2]),
+    /// 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,
@@ -254,7 +259,6 @@ impl Node {
     /// Creates a [`Publisher`][1].
     ///
     /// [1]: crate::Publisher
-    // TODO: make publisher's lifetime depend on node's lifetime
     pub fn create_publisher<T>(
         &self,
         topic: &str,
@@ -270,7 +274,6 @@ impl Node {
     /// Creates a [`Service`][1].
     ///
     /// [1]: crate::Service
-    // TODO: make service's lifetime depend on node's lifetime
     pub fn create_service<T, F>(
         &self,
         topic: &str,
@@ -293,7 +296,6 @@ impl Node {
     /// Creates a [`Subscription`][1].
     ///
     /// [1]: crate::Subscription
-    // TODO: make subscription's lifetime depend on node's lifetime
     pub fn create_subscription<T, Args>(
         &self,
         topic: &str,

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
@@ -298,7 +296,7 @@ impl NodeOptions {
 
         let handle = Arc::new(NodeHandle {
             rcl_node: Mutex::new(rcl_node),
-            context_handle: Arc::clone(&context),
+            context_handle: Arc::clone(context),
         });
         let parameter = {
             let rcl_node = handle.rcl_node.lock().unwrap();

rclrs/src/publisher.rs

@@ -50,9 +50,9 @@ impl Drop for PublisherHandle {
 /// 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::spin
+/// [2]: crate::Executor::spin
 pub struct Publisher<T>
 where
     T: Message,

rclrs/src/subscription.rs

@@ -66,16 +66,15 @@ pub trait SubscriptionBase: Send + Sync {
 ///
 /// There can be multiple subscriptions for the same topic, in different nodes or the same node.
 ///
-/// Receiving messages requires calling [`spin_once`][1] or [`spin`][2] on the subscription's node.
+/// Receiving messages requires the node's executor to [spin][2].
 ///
 /// When a subscription is created, it may take some time to get "matched" with a corresponding
 /// publisher.
 ///
 /// The only available way to instantiate subscriptions is via [`Node::create_subscription()`][3], this
 /// is to ensure that [`Node`][4]s can track all the subscriptions that have been created.
 ///
-/// [1]: crate::spin_once
-/// [2]: crate::spin
+/// [2]: crate::Executor::spin
 /// [3]: crate::Node::create_subscription
 /// [4]: crate::Node
 pub struct Subscription<T>