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

@@ -78,7 +78,7 @@ fn yak_shaving() {
 }
 
 let (subscriber, handle) = subscriber::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::subscriber::with_default;
-use tracing_mock::{subscriber, expect, field};
+use tracing_mock::{subscriber, expect};
 
 #[tracing::instrument]
 fn yak_shaving(number_of_yaks: u32) {
@@ -128,15 +128,15 @@ let (subscriber, handle) = subscriber::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(),
         ),
     )
@@ -173,4 +173,4 @@ This project is licensed under the [MIT license][mit-url].
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in Tracing by you, shall be licensed as MIT, without any additional
-terms or conditions.
+terms or conditions.

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()