mock: document public APIs in subscriber module (#2446)

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 `subscriber` module needs documentation and examples.

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

The `MockSubscriberBuilder::record` method was removed as its
functionality is not implemented.

Previously, the `MockSubscriber` would verify the scope of an
`ExpectedEvent`, even if `in_scope` hadn't been called. In this case,
that would check that an event was not in a span if `in_scope` had not
been called. `tracing-subscriber` all adhere to this pattern. However it
is different to the behavior of all other expectation methods, where an
explicit call is needed to expect something, otherwise nothing is
checked. As such, the behavior has been modified to align with the rest
of the crate. The previous behavior can be achieved by calling
`in_scope(None)` to verify that an event has no scope. The documentation
for `in_scope` has been updated with an example for this case.

The tests in `tracing-subscriber` which previously verified *implicitly*
that an event had no scope (by not calling `in_scope` at all) have *not*
been modified. It is my opinion that this implicit behavior was never
required.

Refs: #539

Author: hds

tracing-mock/src/event.rs

@@ -9,7 +9,7 @@
 //!
 //! ```
 //! use tracing::subscriber::with_default;
-//! use tracing_mock::{subscriber, expect};
+//! use tracing_mock::{expect, subscriber};
 //!
 //! let event = expect::event()
 //!     .at_level(tracing::Level::INFO)
@@ -43,7 +43,7 @@ use std::fmt;
 pub struct ExpectedEvent {
     pub(super) fields: Option<field::ExpectedFields>,
     pub(super) parent: Option<Parent>,
-    pub(super) in_spans: Vec<span::ExpectedSpan>,
+    pub(super) in_spans: Option<Vec<span::ExpectedSpan>>,
     pub(super) metadata: ExpectedMetadata,
 }
 
@@ -451,30 +451,28 @@ impl ExpectedEvent {
     /// recorded event, the expectation will fail.
     ///
     /// **Note**: This validation currently only works with a
-    /// [`MockSubscriber`]. If used with a [`MockCollector`], the
+    /// [`MockLayer`]. If used with a [`MockSubscriber`], the
     /// expectation will fail directly as it is unimplemented.
     ///
     /// # Examples
     ///
     /// ```
-    /// use tracing_mock::{expect, subscriber};
-    /// use tracing_subscriber::{
-    ///     filter::filter_fn, registry, subscribe::CollectExt, util::SubscriberInitExt, Subscribe,
-    /// };
+    /// use tracing_mock::{expect, layer};
+    /// use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, Layer};
     ///
     /// let event = expect::event().in_scope([
     ///     expect::span().named("parent_span"),
     ///     expect::span().named("grandparent_span")
     /// ]);
     ///
-    /// let (subscriber, handle) = subscriber::mock()
+    /// let (layer, handle) = layer::mock()
     ///     .enter(expect::span())
     ///     .enter(expect::span())
     ///     .event(event)
     ///     .run_with_handle();
     ///
-    /// let _subscriber = registry()
-    ///     .with(subscriber.with_filter(filter_fn(move |_meta| true)))
+    /// let _subscriber = tracing_subscriber::registry()
+    ///     .with(layer.with_filter(tracing_subscriber::filter::filter_fn(move |_meta| true)))
     ///     .set_default();
     ///
     /// let grandparent = tracing::info_span!("grandparent_span");
@@ -489,23 +487,21 @@ impl ExpectedEvent {
     /// The scope must match exactly, otherwise the expectation will fail:
     ///
     /// ```should_panic
-    /// use tracing_mock::{expect, subscriber};
-    /// use tracing_subscriber::{
-    ///     filter::filter_fn, registry, subscribe::CollectExt, util::SubscriberInitExt, Subscribe,
-    /// };
+    /// use tracing_mock::{expect, layer};
+    /// use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, Layer};
     ///
     /// let event = expect::event().in_scope([
     ///     expect::span().named("parent_span"),
     ///     expect::span().named("grandparent_span")
     /// ]);
     ///
-    /// let (subscriber, handle) = subscriber::mock()
+    /// let (layer, handle) = layer::mock()
     ///     .enter(expect::span())
     ///     .event(event)
     ///     .run_with_handle();
     ///
-    /// let _subscriber = registry()
-    ///     .with(subscriber.with_filter(filter_fn(move |_meta| true)))
+    /// let _subscriber = tracing_subscriber::registry()
+    ///     .with(layer.with_filter(tracing_subscriber::filter::filter_fn(move |_meta| true)))
     ///     .set_default();
     ///
     /// let parent = tracing::info_span!("parent_span");
@@ -514,21 +510,48 @@ impl ExpectedEvent {
     ///
     /// handle.assert_finished();
     /// ```
+    ///
+    /// It is also possible to test that an event has no parent spans
+    /// by passing `None` to `in_scope`. If the event is within a
+    /// span, the test will fail:
+    ///
+    /// ```should_panic
+    /// use tracing_mock::{expect, layer};
+    /// use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, Layer};
+    ///
+    /// let event = expect::event().in_scope(None);
+    ///
+    /// let (layer, handle) = layer::mock()
+    ///     .enter(expect::span())
+    ///     .event(event)
+    ///     .run_with_handle();
+    ///
+    /// let _subscriber = tracing_subscriber::registry()
+    ///     .with(layer.with_filter(tracing_subscriber::filter::filter_fn(move |_meta| true)))
+    ///     .set_default();
+    ///
+    /// let parent = tracing::info_span!("parent_span");
+    /// let _guard = parent.enter();
+    /// tracing::info!(field = &"value");    
+    ///
+    /// handle.assert_finished();
+    /// ```
+    ///
+    /// [`MockLayer`]: struct@crate::layer::MockLayer
     /// [`MockSubscriber`]: struct@crate::subscriber::MockSubscriber
-    /// [`MockCollector`]: struct@crate::subscriber::MockCollector
     #[cfg(feature = "tracing-subscriber")]
     pub fn in_scope(self, spans: impl IntoIterator<Item = span::ExpectedSpan>) -> Self {
         Self {
-            in_spans: spans.into_iter().collect(),
+            in_spans: Some(spans.into_iter().collect()),
             ..self
         }
     }
 
     /// Provides access to the expected scope (spans) for this expected
     /// event.
     #[cfg(feature = "tracing-subscriber")]
-    pub(crate) fn scope_mut(&mut self) -> &mut [span::ExpectedSpan] {
-        &mut self.in_spans[..]
+    pub(crate) fn scope_mut(&mut self) -> Option<&mut [span::ExpectedSpan]> {
+        self.in_spans.as_mut().map(|s| &mut s[..])
     }
 
     pub(crate) fn check(
@@ -596,8 +619,8 @@ impl fmt::Debug for ExpectedEvent {
             s.field("parent", &format_args!("{:?}", parent));
         }
 
-        if !self.in_spans.is_empty() {
-            s.field("in_spans", &self.in_spans);
+        if let Some(in_spans) = &self.in_spans {
+            s.field("in_spans", in_spans);
         }
 
         s.finish()