Add documentation for parameters

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

Author: mxgrey

examples/logging_demo/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "logging_demo"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+rclrs = "0.4"
+example_interfaces = "*"

examples/logging_demo/package.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<?xml-model
+   href="http://download.ros.org/schema/package_format3.xsd"
+   schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>examples_worker_demo</name>
+  <maintainer email="[email protected]">Esteve Fernandez</maintainer>
+  <!-- This project is not military-sponsored, Jacob's employment contract just requires him to use this email address -->
+  <maintainer email="[email protected]">Jacob Hassold</maintainer>
+  <version>0.4.1</version>
+  <description>Package containing an example of how to use a worker in rclrs.</description>
+  <license>Apache License 2.0</license>
+
+  <depend>rclrs</depend>
+  <depend>rosidl_runtime_rs</depend>
+  <depend>example_interfaces</depend>
+
+  <export>
+    <build_type>ament_cargo</build_type>
+  </export>
+</package>

examples/logging_demo/src/main.rs

@@ -0,0 +1,48 @@
+use rclrs::*;
+use std::time::Duration;
+
+fn main() -> Result<(), RclrsError> {
+    let mut executor = Context::default_from_env()?.create_basic_executor();
+    let node = executor.create_node("logging_demo")?;
+
+    let _subscription = node.clone().create_subscription(
+        "logging_demo",
+        move |msg: example_interfaces::msg::String| {
+            let data = msg.data;
+
+            // You can apply modifiers such as .once() to node.logger()
+            // to dictate how the logging behaves.
+            log!(
+                node.logger().once(),
+                "First message: {data}",
+            );
+
+            log!(
+                node.logger().skip_first(),
+                "Subsequent message: {data}",
+            );
+
+            // You can chain multiple modifiers together.
+            log_warn!(
+                node
+                .logger()
+                .skip_first()
+                .throttle(Duration::from_secs(5)),
+                "Throttled message: {data}",
+            );
+        }
+    )?;
+
+    // Any &str can be used as the logger name and have
+    // logging modifiers applied to it.
+    log_info!(
+        "notice".once(),
+        "Ready to begin logging example_interfaces/msg/String messages published to 'logging_demo'.",
+    );
+    log_warn!(
+        "help",
+        "Try running\n \
+        $ ros2 topic pub logging_demo example_interfaces/msg/String \"data: message\"",
+    );
+    executor.spin(SpinOptions::default()).first_error()
+}

rclrs/src/lib.rs

@@ -117,6 +117,62 @@
 //! executor.spin(SpinOptions::default()).first_error()?;
 //! # Ok::<(), RclrsError>(())
 //! ```
+//!
+//! # Logging
+//!
+//! `rclrs` provides the same logging utilites as `rclcpp` and `rclpy` with an
+//! ergonomic Rust API. [`ToLogParams`] can be used to dictate how logging is
+//! performed.
+//!
+//! ```no_run
+//! use rclrs::*;
+//! use std::time::Duration;
+//!
+//! let mut executor = Context::default_from_env()?.create_basic_executor();
+//! let node = executor.create_node("logging_demo")?;
+//!
+//! let _subscription = node.clone().create_subscription(
+//!     "logging_demo",
+//!     move |msg: example_interfaces::msg::String| {
+//!         let data = msg.data;
+//!
+//!         // You can apply modifiers such as .once() to node.logger()
+//!         // to dictate how the logging behaves.
+//!         log!(
+//!             node.logger().once(),
+//!             "First message: {data}",
+//!         );
+//!
+//!         log!(
+//!             node.logger().skip_first(),
+//!             "Subsequent message: {data}",
+//!         );
+//!
+//!         // You can chain multiple modifiers together.
+//!         log_warn!(
+//!             node
+//!             .logger()
+//!             .skip_first()
+//!             .throttle(Duration::from_secs(5)),
+//!             "Throttled message: {data}",
+//!         );
+//!     }
+//! )?;
+//!
+//! // Any &str can be used as the logger name and have
+//! // logging modifiers applied to it.
+//! log_info!(
+//!     "notice".once(),
+//!     "Ready to begin logging example_interfaces/msg/String messages published to 'logging_demo'.",
+//! );
+//! log_warn!(
+//!     "help",
+//!     "Try running\n \
+//!     $ ros2 topic pub logging_demo example_interfaces/msg/String \"data: message\"",
+//! );
+//! executor.spin(SpinOptions::default()).first_error()?;
+//! # Ok::<(), RclrsError>(())
+//! ```
 
 mod arguments;
 mod client;

rclrs/src/logging.rs

@@ -201,7 +201,7 @@ macro_rules! log {
 macro_rules! log_debug {
     ($to_log_params: expr, $($args:tt)*) => {{
         let log_params = $crate::ToLogParams::to_log_params($to_log_params);
-        $crate::log!(crate::ToLogParams::debug(log_params), $($args)*);
+        $crate::log!($crate::ToLogParams::debug(log_params), $($args)*);
     }}
 }
 
@@ -210,7 +210,7 @@ macro_rules! log_debug {
 macro_rules! log_info {
     ($to_log_params: expr, $($args:tt)*) => {{
         let log_params = $crate::ToLogParams::to_log_params($to_log_params);
-        $crate::log!(crate::ToLogParams::info(log_params), $($args)*);
+        $crate::log!($crate::ToLogParams::info(log_params), $($args)*);
     }}
 }
 
@@ -219,7 +219,7 @@ macro_rules! log_info {
 macro_rules! log_warn {
     ($to_log_params: expr, $($args:tt)*) => {{
         let log_params = $crate::ToLogParams::to_log_params($to_log_params);
-        $crate::log!(crate::ToLogParams::warn(log_params), $($args)*);
+        $crate::log!($crate::ToLogParams::warn(log_params), $($args)*);
     }}
 }
 
@@ -228,7 +228,7 @@ macro_rules! log_warn {
 macro_rules! log_error {
     ($to_log_params: expr, $($args:tt)*) => {{
         let log_params = $crate::ToLogParams::to_log_params($to_log_params);
-        $crate::log!(crate::ToLogParams::error(log_params), $($args)*);
+        $crate::log!($crate::ToLogParams::error(log_params), $($args)*);
     }}
 }
 
@@ -237,7 +237,7 @@ macro_rules! log_error {
 macro_rules! log_fatal {
     ($to_log_params: expr, $($args:tt)*) => {{
         let log_params = $crate::ToLogParams::to_log_params($to_log_params);
-        $crate::log!(crate::ToLogParams::fatal(log_params), $($args)*);
+        $crate::log!($crate::ToLogParams::fatal(log_params), $($args)*);
     }}
 }