mock: document public APIs in event module (tokio-rs#2426)

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

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

The following pattern was applied to the description of most methods:
- Short description of expectation
- Additional clarification (where needed)
- Description of cases that cause the expectation to fail
- Examples
  - Successful validation
  - Unsuccesful validation

Two changes were also made in the text provided to the user when an
assertion fails for `with_explicit_parent` or `with_contextual_parent`.

One small API changes is also included:

The method `in_scope` has been placed behind the `tracing-subscriber`
feature flag as it currently only works with the `MockSubscriber`, not
with the `MockCollector`. If the feature flag is active and it is used
to set a non-empty scope, the `MockCollector` will panic with
`unimplemented` during validation.

Refs: tokio-rs#539

tracing-mock/README.md

@@ -82,7 +82,7 @@ let (collector, handle) = collector::mock()
     .only()
     .run_with_handle();
 
-with_default(collector, || {
+with_default(subscriber, || {
     yak_shaving();
 });
 
@@ -118,7 +118,7 @@ fn yak_shaving(number_of_yaks: u32) {
 let yak_count: u32 = 3;
 let span = expect::span().named("yak_shaving");
 
-let (collector, handle) = collector::mock()
+let (subscriber, handle) = subscriber::mock()
     .new_span(
         span.clone()
             .with_fields(expect::field("number_of_yaks").with_value(&yak_count).only()),
@@ -144,7 +144,7 @@ let (collector, handle) = collector::mock()
     .only()
     .run_with_handle();
 
-with_default(collector, || {
+with_default(subscriber, || {
     yak_shaving(yak_count);
 });
 

tracing-mock/src/lib.rs

@@ -26,14 +26,14 @@ impl Parent {
         parent_name: Option<&str>,
         provided_parent: Option<tracing_core::span::Id>,
         ctx: impl std::fmt::Display,
-        collector_name: &str,
+        subscriber_name: &str,
     ) {
         match self {
             Parent::ExplicitRoot => {
                 assert!(
                     provided_parent.is_none(),
                     "[{}] expected {} to be an explicit root, but its parent was actually {:?} (name: {:?})",
-                    collector_name,
+                    subscriber_name,
                     ctx,
                     provided_parent,
                     parent_name,
@@ -51,7 +51,7 @@ impl Parent {
                     Some(expected_parent.as_ref()),
                     parent_name,
                     "[{}] expected {} to have explicit parent {}, but its parent was actually {:?} (name: {:?})",
-                    collector_name,
+                    subscriber_name,
                     ctx,
                     expected_parent,
                     provided_parent,
@@ -70,7 +70,7 @@ impl Parent {
                 assert!(
                     parent_name.is_none(),
                     "[{}] expected {} to be contextual a root, but we were inside span {:?}",
-                    collector_name,
+                    subscriber_name,
                     ctx,
                     parent_name,
                 );
@@ -87,7 +87,7 @@ impl Parent {
                     Some(expected_parent.as_ref()),
                     parent_name,
                     "[{}] expected {} to have contextual parent {:?}, but got {:?}",
-                    collector_name,
+                    subscriber_name,
                     ctx,
                     expected_parent,
                     parent_name,