mock: document public APIs in the field module (#2443)

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

Additionally, the `field::msg` function (which constructs a field with
name "message" and the provided value) was moved to `expect::message`.
This is part of a unification of all expectation constructors inside the
`expect` module.

Refs: #539

Co-authored-by: David Barsky <[email protected]>

Author: hds

tracing-mock/README.md

@@ -71,14 +71,14 @@ Below is an example that checks that an event contains a message:
 
 ```rust
 use tracing::collect::with_default;
-use tracing_mock::{collector, expect, field};
+use tracing_mock::{collector, expect};
 
 fn yak_shaving() {
     tracing::info!("preparing to shave yaks");
 }
 
 let (collector, handle) = collector::mock()
-    .event(expect::event().with_fields(field::msg("preparing to shave yaks")))
+    .event(expect::event().with_fields(expect::message("preparing to shave yaks")))
     .only()
     .run_with_handle();
 
@@ -102,7 +102,7 @@ Below is a slightly more complex example. `tracing-mock` asserts that, in order:
 
 ```rust
 use tracing::collect::with_default;
-use tracing_mock::{collector, expect, field};
+use tracing_mock::{collector, expect};
 
 #[tracing::instrument]
 fn yak_shaving(number_of_yaks: u32) {
@@ -128,15 +128,15 @@ let (collector, handle) = collector::mock()
         expect::event().with_fields(
             expect::field("number_of_yaks")
                 .with_value(&yak_count)
-                .and(field::msg("preparing to shave yaks"))
+                .and(expect::message("preparing to shave yaks"))
                 .only(),
         ),
     )
     .event(
         expect::event().with_fields(
             expect::field("all_yaks_shaved")
                 .with_value(&true)
-                .and(field::msg("yak shaving completed."))
+                .and(expect::message("yak shaving completed."))
                 .only(),
         ),
     )

tracing-mock/src/collector.rs

@@ -12,7 +12,7 @@
 //!
 //! let (collector, handle) = collector::mock()
 //!     // Expect a single event with a specified message
-//!     .event(expect::event().with_fields(field::msg("droids")))
+//!     .event(expect::event().with_fields(expect::message("droids")))
 //!     .only()
 //!     .run_with_handle();
 //!
@@ -40,7 +40,7 @@
 //!     // Enter a matching span
 //!     .enter(span.clone())
 //!     // Record an event with message "collect parting message"
-//!     .event(expect::event().with_fields(field::msg("collect parting message")))
+//!     .event(expect::event().with_fields(expect::message("collect parting message")))
 //!     // Record a value for the field `parting` on a matching span
 //!     .record(span.clone(), expect::field("parting").with_value(&"goodbye world!"))
 //!     // Exit a matching span
@@ -81,7 +81,7 @@
 //!     .named("my_span");
 //! let (collector, handle) = collector::mock()
 //!     .enter(span.clone())
-//!     .event(expect::event().with_fields(field::msg("collect parting message")))
+//!     .event(expect::event().with_fields(expect::message("collect parting message")))
 //!     .record(span.clone(), expect::field("parting").with_value(&"goodbye world!"))
 //!     .exit(span)
 //!     .only()
@@ -221,7 +221,7 @@ pub struct MockHandle(Arc<Mutex<VecDeque<Expect>>>, String);
 ///     // Enter a matching span
 ///     .enter(span.clone())
 ///     // Record an event with message "collect parting message"
-///     .event(expect::event().with_fields(field::msg("collect parting message")))
+///     .event(expect::event().with_fields(expect::message("collect parting message")))
 ///     // Record a value for the field `parting` on a matching span
 ///     .record(span.clone(), expect::field("parting").with_value(&"goodbye world!"))
 ///     // Exit a matching span

tracing-mock/src/event.rs

@@ -48,7 +48,7 @@ pub struct ExpectedEvent {
 }
 
 pub fn msg(message: impl fmt::Display) -> ExpectedEvent {
-    expect::event().with_fields(field::msg(message))
+    expect::event().with_fields(expect::message(message))
 }
 
 impl ExpectedEvent {

tracing-mock/src/expect.rs

@@ -38,6 +38,13 @@ where
     }
 }
 
+pub fn message(message: impl fmt::Display) -> ExpectedField {
+    ExpectedField {
+        name: "message".to_string(),
+        value: ExpectedValue::Debug(message.to_string()),
+    }
+}
+
 pub fn span() -> ExpectedSpan {
     ExpectedSpan {
         ..Default::default()