attributes: improve docs; tests for using Levels in #[instrument] (t…

…okio-rs#2350)

This branch adds documentation and tests noting that the `#[instrument]`
macro accepts `tracing::Level` directly. Using `tracing::Level` directly
allows for IDE autocomplete and earlier detection of typos.

The documentation for tracing-attributes was also rewritten to remove
the usage of the second-person perspective, making it more consistent
with the rest of tracing's documentation.

Co-authored-by: David Barsky <me@davidbarsky.com>
; Conflicts:
;	tracing-attributes/Cargo.toml
;	tracing-attributes/src/lib.rs

tracing-attributes/src/lib.rs

@@ -113,8 +113,6 @@ mod expand;
 /// for each field. The name of the field must be a single valid Rust
 /// identifier, nested (dotted) field names are not supported.
 ///
-/// This supports the same [field syntax] as the `span!` and `event!` macros.
-///
 /// Note that overlap between the names of fields and (non-skipped) arguments
 /// will result in a compile error.
 ///

tracing-attributes/tests/err.rs

@@ -274,7 +274,7 @@ fn test_err_info() {
         .drop_span(span)
         .only()
         .run_with_handle();
-    with_default(collector, || err_info().ok());
+    with_default(subscriber, || err_info().ok());
     handle.assert_finished();
 }
 
@@ -303,7 +303,7 @@ fn test_err_dbg_info() {
         .drop_span(span)
         .only()
         .run_with_handle();
-    with_default(collector, || err_dbg_info().ok());
+    with_default(subscriber, || err_dbg_info().ok());
     handle.assert_finished();
 }
 
@@ -323,6 +323,6 @@ fn test_err_warn_info() {
         .drop_span(span)
         .only()
         .run_with_handle();
-    with_default(collector, || err_warn_info().ok());
+    with_default(subscriber, || err_warn_info().ok());
     handle.assert_finished();
 }

tracing-attributes/tests/levels.rs

@@ -140,3 +140,49 @@ fn enum_levels() {
 
     handle.assert_finished();
 }
+
+#[test]
+fn enum_levels() {
+    #[instrument(level = Level::TRACE)]
+    fn trace() {}
+
+    #[instrument(level = Level::DEBUG)]
+    fn debug() {}
+
+    #[instrument(level = tracing::Level::INFO)]
+    fn info() {}
+
+    #[instrument(level = Level::WARN)]
+    fn warn() {}
+
+    #[instrument(level = Level::ERROR)]
+    fn error() {}
+    let (subscriber, handle) = subscriber::mock()
+        .new_span(span::mock().named("trace").at_level(Level::TRACE))
+        .enter(span::mock().named("trace").at_level(Level::TRACE))
+        .exit(span::mock().named("trace").at_level(Level::TRACE))
+        .new_span(span::mock().named("debug").at_level(Level::DEBUG))
+        .enter(span::mock().named("debug").at_level(Level::DEBUG))
+        .exit(span::mock().named("debug").at_level(Level::DEBUG))
+        .new_span(span::mock().named("info").at_level(Level::INFO))
+        .enter(span::mock().named("info").at_level(Level::INFO))
+        .exit(span::mock().named("info").at_level(Level::INFO))
+        .new_span(span::mock().named("warn").at_level(Level::WARN))
+        .enter(span::mock().named("warn").at_level(Level::WARN))
+        .exit(span::mock().named("warn").at_level(Level::WARN))
+        .new_span(span::mock().named("error").at_level(Level::ERROR))
+        .enter(span::mock().named("error").at_level(Level::ERROR))
+        .exit(span::mock().named("error").at_level(Level::ERROR))
+        .done()
+        .run_with_handle();
+
+    with_default(subscriber, || {
+        trace();
+        debug();
+        info();
+        warn();
+        error();
+    });
+
+    handle.assert_finished();
+}

tracing-attributes/tests/ret.rs

@@ -343,7 +343,7 @@ fn ret_warn_info() -> i32 {
 #[test]
 fn test_warn_info() {
     let span = span::mock().named("ret_warn_info").at_level(Level::WARN);
-    let (collector, handle) = collector::mock()
+    let (subscriber, handle) = subscriber::mock()
         .new_span(span.clone())
         .enter(span.clone())
         .event(
@@ -356,7 +356,7 @@ fn test_warn_info() {
         .done()
         .run_with_handle();
 
-    with_default(collector, ret_warn_info);
+    with_default(subscriber, ret_warn_info);
     handle.assert_finished();
 }
 
@@ -368,7 +368,7 @@ fn ret_dbg_warn() -> i32 {
 #[test]
 fn test_dbg_warn() {
     let span = span::mock().named("ret_dbg_warn").at_level(Level::INFO);
-    let (collector, handle) = collector::mock()
+    let (subscriber, handle) = subscriber::mock()
         .new_span(span.clone())
         .enter(span.clone())
         .event(
@@ -381,6 +381,6 @@ fn test_dbg_warn() {
         .done()
         .run_with_handle();
 
-    with_default(collector, ret_dbg_warn);
+    with_default(subscriber, ret_dbg_warn);
     handle.assert_finished();
 }