Add doc comments for detal and Fix example code

Author: Soya-Onishi

rclrs/src/context.rs

@@ -118,31 +118,6 @@ impl Context {
         NodeBuilder::new(node_name, self).build()
     }
 
-    /// Creates a new node in a namespace.
-    ///
-    /// Convenience function equivalent to [`Node::new_with_namespace`][1].
-    /// Please see that function's documentation.
-    ///
-    /// [1]: crate::Node::new_with_namespace
-    ///
-    /// # Example
-    /// ```
-    /// # use rclrs::{Context, RclReturnCode};
-    /// let ctx = Context::new([])?;
-    /// let node = ctx.create_node_with_namespace("/my/nested/namespace", "my_node");
-    /// assert!(node.is_ok());
-    /// # Ok::<(), RclReturnCode>(())
-    /// ```
-    pub fn create_node_with_namespace(
-        &self,
-        node_namespace: &str,
-        node_name: &str,
-    ) -> Result<Node, RclReturnCode> {
-        NodeBuilder::new(node_name, self)
-            .namespace(node_namespace)
-            .build()
-    }
-
     /// Creates a [`NodeBuilder`][1].
     ///
     /// Convenience function equivalent to [`NodeBuilder::new`][2].

rclrs/src/node/mod.rs

@@ -42,7 +42,7 @@ pub struct Node {
 
 /// A builder for node instantiation.
 ///
-/// The default values for each field are
+/// default value in each fields are
 ///   - context: user defined
 ///   - name: user defined
 ///   - namespace: "/"
@@ -86,67 +86,6 @@ impl Node {
         NodeBuilder::new(node_name, context).build()
     }
 
-    /// Creates a new node in a namespace.
-    ///
-    /// A namespace without a leading forward slash is automatically changed to have a leading
-    /// forward slash.
-    ///
-    /// # Naming
-    /// The node namespace will be prefixed to the node name itself to form the *fully qualified
-    /// node name*. This is the name that is shown e.g. in `ros2 node list`.
-    /// Similarly, the node namespace will be prefixed to all names of topics and services
-    /// created from this node.
-    ///
-    /// By convention, a node name with a leading underscore marks the node as hidden.
-    ///
-    /// It's a good idea for node names in the same executable to be unique.
-    ///
-    /// ## Remapping
-    /// The namespace and name given here can be overriden through the command line.
-    /// In that sense, the parameters to this 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.
-    ///
-    /// ## Rules for valid names
-    /// The node namespace needs to fulfill the criteria of
-    /// [`rmw_validate_namespace()`][2], otherwise an error will be returned.
-    /// Likewise, the node name needs to fulfill the criteria of [`rmw_validate_node_name()`][3].
-    ///
-    /// # Example
-    /// ```
-    /// # use rclrs::{Context, Node, RclReturnCode, NodeErrorCode};
-    /// let ctx = Context::new([])?;
-    /// // This is a valid namespace and name
-    /// assert!(Node::new_with_namespace("/my/nested/namespace", "my_node", &ctx).is_ok());
-    /// // This name contains invalid characters, although the empty namespace is valid
-    /// assert_eq!(
-    ///     Node::new_with_namespace("", "röböt", &ctx),
-    ///     Err(RclReturnCode::NodeError(NodeErrorCode::NodeInvalidName))
-    /// );
-    /// // This namespace starts with a number
-    /// assert_eq!(
-    ///     Node::new_with_namespace("/123/4", "my_node", &ctx),
-    ///     Err(RclReturnCode::NodeError(NodeErrorCode::NodeInvalidNamespace))
-    /// );
-    /// # Ok::<(), RclReturnCode>(())
-    /// ```
-    ///
-    /// # Panics
-    /// When the node namespace or node name contain interior null bytes.
-    ///
-    /// [1]: https://docs.ros.org/en/rolling/How-To-Guides/Node-arguments.html
-    /// [2]: https://docs.ros2.org/latest/api/rmw/validate__namespace_8h.html
-    /// [3]: https://docs.ros2.org/latest/api/rmw/validate__node__name_8h.html
-    pub fn new_with_namespace(
-        node_ns: &str,
-        node_name: &str,
-        context: &Context,
-    ) -> Result<Node, RclReturnCode> {
-        NodeBuilder::new(node_name, context)
-            .namespace(node_ns)
-            .build()
-    }
-
     /// Returns the name of the node.
     ///
     /// This returns the name after remapping, so it is not necessarily the same as the name that
@@ -180,7 +119,10 @@ impl Node {
     /// # use rclrs::{Context, RclReturnCode};
     /// // Without remapping
     /// let context = Context::new([])?;
-    /// let node = context.create_node_with_namespace("/my/namespace", "my_node")?;
+    /// let node = context
+    ///   .create_node_builder("my_node")
+    ///   .namespace("/my/namespace")
+    ///   .build()?;
     /// assert_eq!(node.namespace(), "/my/namespace");
     /// // With remapping
     /// let remapping = ["--ros-args", "-r", "__ns:=/your_namespace"].map(String::from);
@@ -202,7 +144,10 @@ impl Node {
     /// ```
     /// # use rclrs::{Context, RclReturnCode};
     /// let context = Context::new([])?;
-    /// let node = context.create_node_with_namespace("/my/namespace", "my_node")?;
+    /// let node = context
+    ///   .create_node_builder("my_node")
+    ///   .namespace("/my/namespace")
+    ///   .build()?;
     /// assert_eq!(node.fully_qualified_name(), "/my/namespace/my_node");
     /// # Ok::<(), RclReturnCode>(())
     /// ```
@@ -308,6 +253,45 @@ impl Node {
 
 impl NodeBuilder {
     /// Creates new builder for Node.
+    ///
+    /// # Naming rule for node name
+    /// The node name must follow below rules.
+    ///   - must not be an empty.
+    ///   - must only contain alphanumeric characters and underscores(a-z|A-Z|0-9|_).
+    ///   - must not start a number.
+    /// The validation performs at [`NodeBuilder::build()`][1], and does not perform in this function.
+    /// For more details, see [`rmw_validate_nodename`][2].
+    ///
+    /// By convention, a node name with a leading underscore marks the node as hidden.
+    /// Fully qualified node names(namespace + name) should be unique in the same executable to be unique.
+    ///
+    /// # Remapping
+    /// The namespace and name given here can be overriden through the command line.
+    /// In that sense, the parameters to this constructor and
+    /// [`NodeBuilder::namespace()`][3] are only the _default_ namespace and name.
+    /// See also the [official tutorial][4] on the command line arguments for ROS nodes, and
+    /// the [`Node::namespace()`] and [`Node::name()`] functions for examples.
+    ///
+    /// # Example
+    /// ```
+    /// # use rclrs::{Context, Node, NodeBuilder, RclReturnCode, NodeErrorCode};
+    /// let context = Context::new([])?;
+    /// let builder = NodeBuilder::new("foo_node", &context);
+    /// let node = builder.build()?;
+    /// assert_eq!(node.name(), "foo_node");
+    /// // invalid node name
+    /// let builder = NodeBuilder::new("123abc", &context);
+    /// assert_eq!(
+    ///   builder.build(),
+    ///   Err(RclReturnCode::NodeError(NodeErrorCode::NodeInvalidName))
+    /// );
+    /// # Ok::<(), RclReturnCode>(())
+    /// ```    
+    ///    
+    /// [1]: NodeBuilder::build
+    /// [2]: https://docs.ros2.org/bouncy/api/rmw/validate__node__name_8h.html
+    /// [3]: NodeBuilder::namespace
+    /// [4]: https://docs.ros.org/en/rolling/How-To-Guides/Node-arguments.html
     pub fn new(name: &str, context: &Context) -> NodeBuilder {
         NodeBuilder {
             context: context.handle.clone(),
@@ -317,12 +301,76 @@ impl NodeBuilder {
     }
 
     /// Sets node namespace.
+    ///
+    /// # Naming rule for node namespace
+    /// The node namespace naming rules is based on rules defined for a [topic][1].    
+    /// namespace naming rules are below.
+    ///   - must not be empty(Note that empty string is allowed in this method. Empty string is replaced to "/".)
+    ///   - may contain alphanumric characters, underscores, or forward slashes(a-z|A-Z|0-9|_|/)
+    ///   - must no start with numeric character(0-9)
+    ///   - must not contain repeated forward slashes(/)
+    ///   - must not contain repeated underscores(_)
+    ///
+    /// In fully qualified name, Namespace will be prefixed to node name.
+    /// e.g. `/foo/bar/node_name` when namespace is `/foo/bar` and node name is `node_name`
+    ///
+    /// Note that namespace naming validation is delayed to [`NodeBuilder::build()`][2].
+    /// For more details, see [`rmw_validate_namespace()`][3].
+    ///     
+    /// [1]: http://design.ros2.org/articles/topic_and_service_names.html
+    /// [2]: NodeBuilder::build
+    /// [3]: https://docs.ros2.org/bouncy/api/rmw/validate__namespace_8h.html
+    ///
+    /// # Example
+    /// ```
+    /// # use rclrs::{Context, Node, NodeBuilder, RclReturnCode, NodeErrorCode};
+    /// let context = Context::new([])?;
+    /// let builder = NodeBuilder::new("node_name", &context);
+    /// let node = builder.namespace("/foo/bar").build()?;    
+    /// assert_eq!(node.fully_qualified_name(), "/foo/bar/node_name");
+    /// // invalid namespace
+    /// let builder = NodeBuilder::new("node_name", &context);
+    /// assert_eq!(
+    ///   builder.namespace("123abc").build(),
+    ///   Err(RclReturnCode::NodeError(NodeErrorCode::NodeInvalidNamespace))
+    /// );
+    /// # Ok::<(), RclReturnCode>(())
+    /// ```
     pub fn namespace(mut self, namespace: &str) -> Self {
         self.namespace = namespace.to_string();
         self
     }
 
-    /// Builds node instance    
+    /// Builds node instance
+    ///
+    /// Node name and namespace validation is performed in this method.
+    /// If invalid name and/or namespace are specified to builder,
+    /// this method will return RclReturnCode as error.
+    ///
+    /// # Example
+    /// ```
+    /// # use rclrs::{Context, Node, NodeBuilder, RclReturnCode, NodeErrorCode};
+    /// let context = Context::new([])?;
+    ///
+    /// let builder = NodeBuilder::new("node_name", &context);
+    /// let result = builder.namespace("/foo/bar").build();
+    /// assert!(result.is_ok());
+    /// // invalid node name
+    /// let builder = NodeBuilder::new("123abc", &context);
+    /// let result = builder.namespace("/foo/bar").build();
+    /// assert_eq!(
+    ///   result,
+    ///   Err(RclReturnCode::NodeError(NodeErrorCode::NodeInvalidName))
+    /// );
+    /// // invalid namespace
+    /// let builder = NodeBuilder::new("node_name", &context);
+    /// let result = builder.namespace("123abc").build();
+    /// assert_eq!(
+    ///   result,
+    ///   Err(RclReturnCode::NodeError(NodeErrorCode::NodeInvalidNamespace))
+    /// );
+    /// # Ok::<(), RclReturnCode>(())
+    /// ```
     pub fn build(&self) -> Result<Node, RclReturnCode> {
         let node_name = CString::new(self.name.as_str()).unwrap();
         let node_namespace = CString::new(self.namespace.as_str()).unwrap();