mock: document public APIs in subscriber module

[hds]

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

Solution

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

[hawkw]

thanks for adding the docs! i left some small wording suggestions

[hawkw]

Okay, this looks good to me.

@davidbarsky, do you also want to take a look at the docs? If not, I'm happy to merge this PR.

[davidbarsky]

@davidbarsky, do you also want to take a look at the docs? If not, I'm happy to merge this PR.

@hawkw no, let's land these.