mock: document public APIs in span module (#2442)

This change adds documentation to the tracing-mock span module and all
the public APIs within it. This includes doctests on all the methods
which serve as examples.

Additionally, the validation on `ExpectedSpan` was improved so that it
validates the level and target during `enter` and `exit` as well as on
`new_span`.

The method `ExpectedSpan::with_field` was renamed to `with_fields`
(plural) to match the same method on `ExpectedEvent` (and because
multiple fields can be passed to it).

A copy-paste typo was also fixed in the documentation for
`ExpectedEvent::with_contextual_parent`.

Refs: #539

Co-authored-by: David Barsky <me@davidbarsky.com>

tracing-attributes/tests/async_fn.rs

@@ -199,8 +199,8 @@ fn async_fn_with_async_trait() {
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone()
-                .with_field(expect::field("self"))
-                .with_field(expect::field("v")),
+                .with_fields(expect::field("self"))
+                .with_fields(expect::field("v")),
         )
         .enter(span.clone())
         .new_span(span3.clone())
@@ -210,7 +210,7 @@ fn async_fn_with_async_trait() {
         .enter(span3.clone())
         .exit(span3.clone())
         .drop_span(span3)
-        .new_span(span2.clone().with_field(expect::field("self")))
+        .new_span(span2.clone().with_fields(expect::field("self")))
         .enter(span2.clone())
         .event(expect::event().with_fields(expect::field("val").with_value(&5u64)))
         .exit(span2.clone())
@@ -260,7 +260,7 @@ fn async_fn_with_async_trait_and_fields_expressions() {
     let span = expect::span().named("call");
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("_v")
                     .with_value(&5usize)
                     .and(expect::field("test").with_value(&tracing::field::debug(10)))
@@ -330,21 +330,21 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
     let span4 = expect::span().named("sync_fun");
     let (subscriber, handle) = subscriber::mock()
         /*.new_span(span.clone()
-            .with_field(
+            .with_fields(
                 expect::field("Self").with_value(&"TestImpler")))
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)*/
         .new_span(
             span2
                 .clone()
-                .with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
+                .with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
         )
         .enter(span2.clone())
         .new_span(
             span4
                 .clone()
-                .with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
+                .with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
         )
         .enter(span4.clone())
         .exit(span4.clone())
@@ -357,7 +357,7 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
         .new_span(
             span3
                 .clone()
-                .with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
+                .with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
         )
         .enter(span3.clone())
         .exit(span3.clone())

tracing-attributes/tests/destructuring.rs

@@ -11,7 +11,7 @@ fn destructure_tuples() {
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&format_args!("1"))
                     .and(expect::field("arg2").with_value(&format_args!("2")))
@@ -40,7 +40,7 @@ fn destructure_nested_tuples() {
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&format_args!("1"))
                     .and(expect::field("arg2").with_value(&format_args!("2")))
@@ -72,7 +72,7 @@ fn destructure_refs() {
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone()
-                .with_field(expect::field("arg1").with_value(&1usize).only()),
+                .with_fields(expect::field("arg1").with_value(&1usize).only()),
         )
         .enter(span.clone())
         .exit(span.clone())
@@ -98,7 +98,7 @@ fn destructure_tuple_structs() {
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&format_args!("1"))
                     .and(expect::field("arg2").with_value(&format_args!("2")))
@@ -139,7 +139,7 @@ fn destructure_structs() {
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&format_args!("1"))
                     .and(expect::field("arg2").with_value(&format_args!("2")))
@@ -184,7 +184,7 @@ fn destructure_everything() {
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&format_args!("1"))
                     .and(expect::field("arg2").with_value(&format_args!("2")))

tracing-attributes/tests/err.rs

@@ -159,7 +159,7 @@ fn impl_trait_return_type() {
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone()
-                .with_field(expect::field("x").with_value(&10usize).only()),
+                .with_fields(expect::field("x").with_value(&10usize).only()),
         )
         .enter(span.clone())
         .exit(span.clone())

tracing-attributes/tests/fields.rs

@@ -46,7 +46,7 @@ impl HasField {
 
 #[test]
 fn fields() {
-    let span = expect::span().with_field(
+    let span = expect::span().with_fields(
         expect::field("foo")
             .with_value(&"bar")
             .and(expect::field("dsa").with_value(&true))
@@ -60,7 +60,7 @@ fn fields() {
 
 #[test]
 fn expr_field() {
-    let span = expect::span().with_field(
+    let span = expect::span().with_fields(
         expect::field("s")
             .with_value(&"hello world")
             .and(expect::field("len").with_value(&"hello world".len()))
@@ -73,7 +73,7 @@ fn expr_field() {
 
 #[test]
 fn two_expr_fields() {
-    let span = expect::span().with_field(
+    let span = expect::span().with_fields(
         expect::field("s")
             .with_value(&"hello world")
             .and(expect::field("s.len").with_value(&"hello world".len()))
@@ -87,7 +87,7 @@ fn two_expr_fields() {
 
 #[test]
 fn clashy_expr_field() {
-    let span = expect::span().with_field(
+    let span = expect::span().with_fields(
         // Overriding the `s` field should record `s` as a `Display` value,
         // rather than as a `Debug` value.
         expect::field("s")
@@ -99,7 +99,7 @@ fn clashy_expr_field() {
         fn_clashy_expr_field("hello world");
     });
 
-    let span = expect::span().with_field(expect::field("s").with_value(&"s").only());
+    let span = expect::span().with_fields(expect::field("s").with_value(&"s").only());
     run_test(span, || {
         fn_clashy_expr_field2("hello world");
     });
@@ -108,7 +108,7 @@ fn clashy_expr_field() {
 #[test]
 fn self_expr_field() {
     let span =
-        expect::span().with_field(expect::field("my_field").with_value(&"hello world").only());
+        expect::span().with_fields(expect::field("my_field").with_value(&"hello world").only());
     run_test(span, || {
         let has_field = HasField {
             my_field: "hello world",
@@ -119,7 +119,7 @@ fn self_expr_field() {
 
 #[test]
 fn parameters_with_fields() {
-    let span = expect::span().with_field(
+    let span = expect::span().with_fields(
         expect::field("foo")
             .with_value(&"bar")
             .and(expect::field("param").with_value(&1u32))
@@ -132,15 +132,15 @@ fn parameters_with_fields() {
 
 #[test]
 fn empty_field() {
-    let span = expect::span().with_field(expect::field("foo").with_value(&"bar").only());
+    let span = expect::span().with_fields(expect::field("foo").with_value(&"bar").only());
     run_test(span, || {
         fn_empty_field();
     });
 }
 
 #[test]
 fn string_field() {
-    let span = expect::span().with_field(expect::field("s").with_value(&"hello world").only());
+    let span = expect::span().with_fields(expect::field("s").with_value(&"hello world").only());
     run_test(span, || {
         fn_string(String::from("hello world"));
     });

tracing-attributes/tests/instrument.rs

@@ -64,7 +64,7 @@ fn fields() {
         .with_target("my_target");
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&2usize)
                     .and(expect::field("arg2").with_value(&false))
@@ -76,7 +76,7 @@ fn fields() {
         .exit(span.clone())
         .drop_span(span)
         .new_span(
-            span2.clone().with_field(
+            span2.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&3usize)
                     .and(expect::field("arg2").with_value(&true))
@@ -126,15 +126,15 @@ fn skip() {
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone()
-                .with_field(expect::field("arg1").with_value(&2usize).only()),
+                .with_fields(expect::field("arg1").with_value(&2usize).only()),
         )
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
         .new_span(
             span2
                 .clone()
-                .with_field(expect::field("arg1").with_value(&3usize).only()),
+                .with_fields(expect::field("arg1").with_value(&3usize).only()),
         )
         .enter(span2.clone())
         .exit(span2.clone())
@@ -171,7 +171,7 @@ fn generics() {
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("arg1")
                     .with_value(&format_args!("Foo"))
                     .and(expect::field("arg2").with_value(&format_args!("false"))),
@@ -204,7 +204,7 @@ fn methods() {
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
-            span.clone().with_field(
+            span.clone().with_fields(
                 expect::field("self")
                     .with_value(&format_args!("Foo"))
                     .and(expect::field("arg1").with_value(&42usize)),
@@ -236,7 +236,7 @@ fn impl_trait_return_type() {
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone()
-                .with_field(expect::field("x").with_value(&10usize).only()),
+                .with_fields(expect::field("x").with_value(&10usize).only()),
         )
         .enter(span.clone())
         .exit(span.clone())

tracing-mock/README.md

@@ -121,7 +121,7 @@ let span = expect::span().named("yak_shaving");
 let (subscriber, handle) = subscriber::mock()
     .new_span(
         span.clone()
-            .with_field(expect::field("number_of_yaks").with_value(&yak_count).only()),
+            .with_fields(expect::field("number_of_yaks").with_value(&yak_count).only()),
     )
     .enter(span.clone())
     .event(

tracing-mock/src/event.rs

@@ -364,7 +364,7 @@ impl ExpectedEvent {
     ///
     /// # Examples
     ///
-    /// The explicit parent is matched by name:
+    /// The contextual parent is matched by name:
     ///
     /// ```
     /// use tracing::subscriber::with_default;