Document why ::new needs pub(crate) visibility

Author: esteve

rclrs/src/node/client.rs

@@ -56,6 +56,9 @@ type RequestValue<Response> = Box<dyn FnOnce(Response) + 'static + Send>;
 type RequestId = i64;
 
 /// Main class responsible for sending requests to a ROS service.
+///
+/// The only available way to instantiate clients is via [`Node::create_client`], this is to
+/// ensure that [`Node`]s can track all the clients that have been created.
 pub struct Client<T>
 where
     T: rosidl_runtime_rs::Service,
@@ -71,6 +74,8 @@ where
 {
     /// Creates a new client.
     pub(crate) fn new(node: &Node, topic: &str) -> Result<Self, RclrsError>
+    // This uses pub(crate) visibility to avoid instantiating this struct outside
+    // [`Node::create_client`], see the struct's documentation for the rationale
     where
         T: rosidl_runtime_rs::Service,
     {

rclrs/src/node/service.rs

@@ -55,6 +55,9 @@ type ServiceCallback<Request, Response> =
     Box<dyn Fn(&rmw_request_id_t, Request) -> Response + 'static + Send>;
 
 /// Main class responsible for responding to requests sent by ROS clients.
+///
+/// The only available way to instantiate services is via [`Node::create_service`], this is to
+/// ensure that [`Node`]s can track all the services that have been created.
 pub struct Service<T>
 where
     T: rosidl_runtime_rs::Service,
@@ -70,6 +73,8 @@ where
 {
     /// Creates a new service.
     pub(crate) fn new<F>(node: &Node, topic: &str, callback: F) -> Result<Self, RclrsError>
+    // This uses pub(crate) visibility to avoid instantiating this struct outside
+    // [`Node::create_service`], see the struct's documentation for the rationale
     where
         T: rosidl_runtime_rs::Service,
         F: Fn(&rmw_request_id_t, T::Request) -> T::Response + 'static + Send,

rclrs/src/node/subscription.rs

@@ -59,6 +59,9 @@ pub trait SubscriptionBase: Send + Sync {
 /// 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`], this
+/// is to ensure that [`Node`]s can track all the subscriptions that have been created.
+///
 /// [1]: crate::spin_once
 /// [2]: crate::spin
 pub struct Subscription<T>
@@ -82,6 +85,8 @@ where
         qos: QoSProfile,
         callback: F,
     ) -> Result<Self, RclrsError>
+    // This uses pub(crate) visibility to avoid instantiating this struct outside
+    // [`Node::create_subscription`], see the struct's documentation for the rationale
     where
         T: Message,
         F: FnMut(T) + 'static + Send,