docs(common): add a comment explaining how to use the timer! macro

Author: bnjbvr

crates/matrix-sdk-common/src/tracing_timer.rs

@@ -15,7 +15,7 @@
 use ruma::time::Instant;
 use tracing::{callsite::DefaultCallsite, Callsite as _};
 
-/// A named RAII that will show on Drop how long its covered section took to
+/// A named RAII that will show on `Drop` how long its covered section took to
 /// execute.
 pub struct TracingTimer {
     id: String,
@@ -72,11 +72,29 @@ impl TracingTimer {
     }
 }
 
-/// Macro to create a RAII timer that will log a `tracing` event once it's
-/// dropped.
+/// Macro to create a RAII timer that will log on `Drop` how long its covered
+/// section took to execute.
 ///
 /// The tracing level can be specified as a first argument, but it's optional.
 /// If it's missing, this will use the debug level.
+///
+/// ```rust,no_run
+/// # fn do_long_computation(_x: u32) {}
+/// # fn main() {
+/// use matrix_sdk_common::timer;
+///
+/// // It's possible to specify the tracing level we want to be used for the log message on drop.
+/// {
+///     let _timer = timer!(tracing::Level::TRACE, "do long computation");
+///     // But it's optional; by default it's set to `DEBUG`.
+///     let _debug_timer = timer!("do long computation but time it in DEBUG");
+///     // The macro doesn't support formatting / structured events (yet?), but you can use
+///     // `format!()` for that.
+///     let other_timer = timer!(format!("do long computation for parameter = {}", 123));
+///     do_long_computation(123);
+/// } // The log statements will happen here.
+/// # }
+/// ```
 #[macro_export]
 macro_rules! timer {
     ($level:expr, $string:expr) => {{