mock: complete API documentation including expect module (#2494)

There has been interest around publishing tracing-mock to crates.io
for some time. In order to make this possible, documentation and some
code clean up is needed.

The `expect` module, which contains constructor functions for many of
the other `tracing-mock` modules needs documentation and examples.

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

The lint for `missing_docs` has been enabled for the entire
`tracing-mock` crate! This has been done together with all the
other lints that are enabled on the other crates in this project.

The `event::msg("message")` constructor was removed, in favor of
requiring an explicit construction via
`expect::event().with_fields(expect::msg("message"))`. This is
appropriate to reduce the API surface that would need to be supported in
the future and also because the `event::msg` constructor could be
overridden by a subsequent usage of `with_fields`. The shorthand
`expect::message()` was renamed to `expect::msg` to make this
change less burdensome.

The `span::named("name")` constructor was removed, in favor of requiring
an explicit construction via `expect::span.with_name("name")`. The
latter isn't much longer and since #3097, a string with the name can
be passed directly everywhere that an `ExpectedSpan` is required.

This change also sets the `missing_docs` lint to warn for the entire
`tracing-mock` crate, making it ready to publish (once backported).

Refs: #539

Author: hds

tracing-mock/README.md

@@ -4,7 +4,7 @@
 
 # tracing-mock
 
-Utilities for testing [`tracing`][tracing] and crates that uses it.
+Utilities for testing [`tracing`] and crates that uses it.
 
 [![Documentation (master)][docs-master-badge]][docs-master-url]
 [![MIT licensed][mit-badge]][mit-url]
@@ -71,14 +71,14 @@ Below is an example that checks that an event contains a message:
 
 ```rust
 use tracing::subscriber::with_default;
-use tracing_mock::{subscriber, expect, field};
+use tracing_mock::{expect, subscriber};
 
 fn yak_shaving() {
     tracing::info!("preparing to shave yaks");
 }
 
 let (subscriber, handle) = subscriber::mock()
-    .event(expect::event().with_fields(expect::message("preparing to shave yaks")))
+    .event(expect::event().with_fields(expect::msg("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};
+use tracing_mock::{expect, subscriber};
 
 #[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(expect::message("preparing to shave yaks"))
+                .and(expect::msg("preparing to shave yaks"))
                 .only(),
         ),
     )
     .event(
         expect::event().with_fields(
             expect::field("all_yaks_shaved")
                 .with_value(&true)
-                .and(expect::message("yak shaving completed."))
+                .and(expect::msg("yak shaving completed."))
                 .only(),
         ),
     )

tracing-mock/src/event.rs

@@ -28,16 +28,15 @@
 //!
 //! [`subscriber`]: mod@crate::subscriber
 //! [`expect::event`]: fn@crate::expect::event
-#![allow(missing_docs)]
+use std::fmt;
+
 use crate::{
     ancestry::{ActualAncestry, ExpectedAncestry},
-    expect, field,
+    field,
     metadata::ExpectedMetadata,
     span,
 };
 
-use std::fmt;
-
 /// An expected event.
 ///
 /// For a detailed description and examples, see the documentation for
@@ -52,10 +51,6 @@ pub struct ExpectedEvent {
     pub(super) metadata: ExpectedMetadata,
 }
 
-pub fn msg(message: impl fmt::Display) -> ExpectedEvent {
-    expect::event().with_fields(expect::message(message))
-}
-
 impl ExpectedEvent {
     /// Sets a name to expect when matching an event.
     ///
@@ -100,7 +95,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_fields(expect::field("field.name").with_value(&"field_value"));
@@ -120,7 +115,7 @@ impl ExpectedEvent {
     ///
     /// ```should_panic
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_fields(expect::field("field.name").with_value(&"field_value"));
@@ -156,7 +151,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .at_level(tracing::Level::WARN);
@@ -177,7 +172,7 @@ impl ExpectedEvent {
     ///
     /// ```should_panic
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .at_level(tracing::Level::INFO);
@@ -210,7 +205,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_target("some_target");
@@ -230,7 +225,7 @@ impl ExpectedEvent {
     ///
     /// ```should_panic
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_target("some_target");
@@ -277,7 +272,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let parent = expect::span()
     ///     .named("parent_span")
@@ -304,7 +299,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_ancestry(expect::has_explicit_parent("parent_span"));
@@ -326,7 +321,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_ancestry(expect::is_explicit_root());
@@ -350,7 +345,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_ancestry(expect::has_contextual_parent("parent_span"));
@@ -374,7 +369,7 @@ impl ExpectedEvent {
     ///
     /// ```
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_ancestry(expect::is_contextual_root());
@@ -396,7 +391,7 @@ impl ExpectedEvent {
     ///
     /// ```should_panic
     /// use tracing::subscriber::with_default;
-    /// use tracing_mock::{subscriber, expect};
+    /// use tracing_mock::{expect, subscriber};
     ///
     /// let event = expect::event()
     ///     .with_ancestry(expect::has_contextual_parent("parent_span"));