Skip to content

Commit 1489807

Browse files
mxgreymxgrey
committed
Add documentation for parameters
Signed-off-by: Michael X. Grey <[email protected]>
1 parent 4617c9f commit 1489807

File tree

5 files changed

+138
-5
lines changed

5 files changed

+138
-5
lines changed

‎examples/logging_demo/Cargo.toml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[package]
2+
name = "logging_demo"
3+
version = "0.1.0"
4+
edition = "2024"
5+
6+
[dependencies]
7+
rclrs = "0.4"
8+
example_interfaces = "*"

‎examples/logging_demo/package.xml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?xml version="1.0"?>
2+
<?xml-model
3+
href="http://download.ros.org/schema/package_format3.xsd"
4+
schematypens="http://www.w3.org/2001/XMLSchema"?>
5+
<package format="3">
6+
<name>examples_worker_demo</name>
7+
<maintainer email="[email protected]">Esteve Fernandez</maintainer>
8+
<!-- This project is not military-sponsored, Jacob's employment contract just requires him to use this email address -->
9+
<maintainer email="[email protected]">Jacob Hassold</maintainer>
10+
<version>0.4.1</version>
11+
<description>Package containing an example of how to use a worker in rclrs.</description>
12+
<license>Apache License 2.0</license>
13+
14+
<depend>rclrs</depend>
15+
<depend>rosidl_runtime_rs</depend>
16+
<depend>example_interfaces</depend>
17+
18+
<export>
19+
<build_type>ament_cargo</build_type>
20+
</export>
21+
</package>

‎examples/logging_demo/src/main.rs

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
use rclrs::*;
2+
use std::time::Duration;
3+
4+
fn main() -> Result<(), RclrsError> {
5+
let mut executor = Context::default_from_env()?.create_basic_executor();
6+
let node = executor.create_node("logging_demo")?;
7+
8+
let _subscription = node.clone().create_subscription(
9+
"logging_demo",
10+
move |msg: example_interfaces::msg::String| {
11+
let data = msg.data;
12+
13+
// You can apply modifiers such as .once() to node.logger()
14+
// to dictate how the logging behaves.
15+
log!(
16+
node.logger().once(),
17+
"First message: {data}",
18+
);
19+
20+
log!(
21+
node.logger().skip_first(),
22+
"Subsequent message: {data}",
23+
);
24+
25+
// You can chain multiple modifiers together.
26+
log_warn!(
27+
node
28+
.logger()
29+
.skip_first()
30+
.throttle(Duration::from_secs(5)),
31+
"Throttled message: {data}",
32+
);
33+
}
34+
)?;
35+
36+
// Any &str can be used as the logger name and have
37+
// logging modifiers applied to it.
38+
log_info!(
39+
"notice".once(),
40+
"Ready to begin logging example_interfaces/msg/String messages published to 'logging_demo'.",
41+
);
42+
log_warn!(
43+
"help",
44+
"Try running\n \
45+
$ ros2 topic pub logging_demo example_interfaces/msg/String \"data: message\"",
46+
);
47+
executor.spin(SpinOptions::default()).first_error()
48+
}

‎rclrs/src/lib.rs

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,62 @@
117117
//! executor.spin(SpinOptions::default()).first_error()?;
118118
//! # Ok::<(), RclrsError>(())
119119
//! ```
120+
//!
121+
//! # Logging
122+
//!
123+
//! `rclrs` provides the same logging utilites as `rclcpp` and `rclpy` with an
124+
//! ergonomic Rust API. [`ToLogParams`] can be used to dictate how logging is
125+
//! performed.
126+
//!
127+
//! ```no_run
128+
//! use rclrs::*;
129+
//! use std::time::Duration;
130+
//!
131+
//! let mut executor = Context::default_from_env()?.create_basic_executor();
132+
//! let node = executor.create_node("logging_demo")?;
133+
//!
134+
//! let _subscription = node.clone().create_subscription(
135+
//! "logging_demo",
136+
//! move |msg: example_interfaces::msg::String| {
137+
//! let data = msg.data;
138+
//!
139+
//! // You can apply modifiers such as .once() to node.logger()
140+
//! // to dictate how the logging behaves.
141+
//! log!(
142+
//! node.logger().once(),
143+
//! "First message: {data}",
144+
//! );
145+
//!
146+
//! log!(
147+
//! node.logger().skip_first(),
148+
//! "Subsequent message: {data}",
149+
//! );
150+
//!
151+
//! // You can chain multiple modifiers together.
152+
//! log_warn!(
153+
//! node
154+
//! .logger()
155+
//! .skip_first()
156+
//! .throttle(Duration::from_secs(5)),
157+
//! "Throttled message: {data}",
158+
//! );
159+
//! }
160+
//! )?;
161+
//!
162+
//! // Any &str can be used as the logger name and have
163+
//! // logging modifiers applied to it.
164+
//! log_info!(
165+
//! "notice".once(),
166+
//! "Ready to begin logging example_interfaces/msg/String messages published to 'logging_demo'.",
167+
//! );
168+
//! log_warn!(
169+
//! "help",
170+
//! "Try running\n \
171+
//! $ ros2 topic pub logging_demo example_interfaces/msg/String \"data: message\"",
172+
//! );
173+
//! executor.spin(SpinOptions::default()).first_error()?;
174+
//! # Ok::<(), RclrsError>(())
175+
//! ```
120176
121177
mod arguments;
122178
mod client;

‎rclrs/src/logging.rs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ macro_rules! log {
201201
macro_rules! log_debug {
202202
($to_log_params: expr, $($args:tt)*) => {{
203203
let log_params = $crate::ToLogParams::to_log_params($to_log_params);
204-
$crate::log!(crate::ToLogParams::debug(log_params), $($args)*);
204+
$crate::log!($crate::ToLogParams::debug(log_params), $($args)*);
205205
}}
206206
}
207207

@@ -210,7 +210,7 @@ macro_rules! log_debug {
210210
macro_rules! log_info {
211211
($to_log_params: expr, $($args:tt)*) => {{
212212
let log_params = $crate::ToLogParams::to_log_params($to_log_params);
213-
$crate::log!(crate::ToLogParams::info(log_params), $($args)*);
213+
$crate::log!($crate::ToLogParams::info(log_params), $($args)*);
214214
}}
215215
}
216216

@@ -219,7 +219,7 @@ macro_rules! log_info {
219219
macro_rules! log_warn {
220220
($to_log_params: expr, $($args:tt)*) => {{
221221
let log_params = $crate::ToLogParams::to_log_params($to_log_params);
222-
$crate::log!(crate::ToLogParams::warn(log_params), $($args)*);
222+
$crate::log!($crate::ToLogParams::warn(log_params), $($args)*);
223223
}}
224224
}
225225

@@ -228,7 +228,7 @@ macro_rules! log_warn {
228228
macro_rules! log_error {
229229
($to_log_params: expr, $($args:tt)*) => {{
230230
let log_params = $crate::ToLogParams::to_log_params($to_log_params);
231-
$crate::log!(crate::ToLogParams::error(log_params), $($args)*);
231+
$crate::log!($crate::ToLogParams::error(log_params), $($args)*);
232232
}}
233233
}
234234

@@ -237,7 +237,7 @@ macro_rules! log_error {
237237
macro_rules! log_fatal {
238238
($to_log_params: expr, $($args:tt)*) => {{
239239
let log_params = $crate::ToLogParams::to_log_params($to_log_params);
240-
$crate::log!(crate::ToLogParams::fatal(log_params), $($args)*);
240+
$crate::log!($crate::ToLogParams::fatal(log_params), $($args)*);
241241
}}
242242
}
243243

0 commit comments

Comments
 (0)