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

## Motivation

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.

## Solution

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: #539

Author: hds

tracing-mock/Cargo.toml

@@ -20,7 +20,7 @@ publish = false
 [dependencies]
 tracing = { path = "../tracing", version = "0.2" }
 tracing-core = { path = "../tracing-core", version = "0.2", default-features = false }
-tracing-subscriber = { path = "../tracing-subscriber", version = "0.3", default-features = false, optional = true }
+tracing-subscriber = { path = "../tracing-subscriber", version = "0.3", default-features = false, features = ["registry"], optional = true }
 tokio-test = { version = "0.4.2", optional = true }
 
 # Fix minimal-versions; tokio-test fails with otherwise acceptable 0.1.0

tracing-mock/src/collector.rs

@@ -229,6 +229,14 @@ where
         match self.expected.lock().unwrap().pop_front() {
             None => {}
             Some(Expect::Event(mut expected)) => {
+                #[cfg(feature = "tracing-subscriber")]
+                {
+                    if !expected.scope_mut().is_empty() {
+                        unimplemented!(
+                            "Expected scope for events is not supported with `MockCollector`."
+                        )
+                    }
+                }
                 let get_parent_name = || {
                     let stack = self.current.lock().unwrap();
                     let spans = self.spans.lock().unwrap();