mock: add doctests for on_register_dispatch negative cases (#3416)

## Motivation

In order to add a regression test, #3379 added support to `tracing-mock`
to expect calls to `on_register_dispatch` for both mock subscribers and
mock layers. A negative integration test for the layer case was included
in #3415. However, there are no negative doctests for this (and as per
my own suggestion, there's no negative test for the subscriber method
either as I wasn't sure it was possible).

## Solution

After a bit of thought, I realised that we could include a negative test
for the `MockSubscriber`. This change adds that test as a doctest, since
we have those in almost all of our documentation and also includes the
already written negative test for the `MockLayer` to a doctest.

Author: hds

tracing-mock/src/layer.rs

@@ -671,6 +671,50 @@ impl MockLayerBuilder {
     /// handle.assert_finished();
     /// ```
     ///
+    /// If the `on_register_dispatch` call doesn't make it to the `MockLayer`,
+    /// in case it's wrapped in another Layer that doesn't forward the call,
+    /// then the expectation will fail.
+    ///
+    /// ```should_panic
+    /// # use std::marker::PhantomData;
+    ///
+    /// # use tracing::{Event, Subscriber};
+    /// # use tracing_mock::layer;
+    /// # use tracing_subscriber::{
+    /// #     layer::{Context, SubscriberExt},
+    /// #     util::SubscriberInitExt,
+    /// #     Layer,
+    /// # };
+    ///
+    /// struct WrapLayer<S: Subscriber, L: Layer<S>> {
+    ///     inner: L,
+    ///     _pd: PhantomData<S>,
+    /// }
+    ///
+    /// impl<S: Subscriber, L: Layer<S>> Layer<S> for WrapLayer<S, L> {
+    ///     fn on_register_dispatch(&self, subscriber: &tracing::Dispatch) {
+    ///         // Doesn't forward to `self.inner`
+    ///         let _ = subscriber;
+    ///     }
+    ///
+    ///     fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) {
+    ///         self.inner.on_event(event, ctx)
+    ///     }
+    /// }
+    /// let (layer, handle) = layer::mock().on_register_dispatch().run_with_handle();
+    /// let wrap_layer = WrapLayer {
+    ///     inner: layer,
+    ///     _pd: PhantomData::<_>,
+    /// };
+    ///
+    /// let subscriber = tracing_subscriber::registry().with(wrap_layer).set_default();
+    ///
+    /// // The layer's on_register_dispatch is called when the subscriber is set as default
+    /// drop(subscriber);
+    ///
+    /// handle.assert_finished();
+    /// ```
+    ///
     /// [`Layer::on_register_dispatch`]: tracing_subscriber::layer::Layer::on_register_dispatch
     pub fn on_register_dispatch(mut self) -> Self {
         self.expected.push_back(Expect::OnRegisterDispatch);

tracing-mock/src/subscriber.rs

@@ -827,6 +827,58 @@ where
     /// handle.assert_finished();
     /// ```
     ///
+    ///
+    /// ```should_panic
+    /// use tracing_mock::{subscriber};
+    ///
+    /// struct WrapSubscriber<S: tracing::Subscriber> {
+    ///     inner: S,
+    /// }
+    ///
+    /// impl<S: tracing::Subscriber> tracing::Subscriber for WrapSubscriber<S> {
+    /// #     fn enabled(&self, metadata: &tracing::Metadata<'_>) -> bool {
+    /// #         self.inner.enabled(metadata)
+    /// #     }
+    /// #     fn new_span(&self, span: &tracing_core::span::Attributes<'_>) -> tracing_core::span::Id {
+    /// #         self.inner.new_span(span)
+    /// #     }
+    /// #     fn record(&self, span: &tracing_core::span::Id, values: &tracing_core::span::Record<'_>) {
+    /// #         self.inner.record(span, values)
+    /// #     }
+    /// #     fn record_follows_from(
+    /// #         &self,
+    /// #         span: &tracing_core::span::Id,
+    /// #         follows: &tracing_core::span::Id,
+    /// #     ) {
+    /// #         self.inner.record_follows_from(span, follows)
+    /// #     }
+    /// #     fn event(&self, event: &tracing::Event<'_>) {
+    /// #         self.inner.event(event)
+    /// #     }
+    /// #     fn enter(&self, span: &tracing_core::span::Id) {
+    /// #         self.inner.enter(span)
+    /// #     }
+    /// #     fn exit(&self, span: &tracing_core::span::Id) {
+    /// #         self.inner.exit(span)
+    /// #     }
+    ///     // All other Subscriber methods implemented to forward correctly.
+    ///
+    ///     fn on_register_dispatch(&self, subscriber: &tracing::Dispatch) {
+    ///         // Doesn't forward to `self.inner`
+    ///         let _ = subscriber;
+    ///     }
+    /// }
+    ///
+    /// let (subscriber, handle) = subscriber::mock().on_register_dispatch().run_with_handle();
+    /// let wrap_subscriber = WrapSubscriber { inner: subscriber };
+    ///
+    /// tracing::subscriber::with_default(wrap_subscriber, || {
+    ///     // The subscriber's on_register_dispatch is called when set as default
+    /// });
+    ///
+    /// handle.assert_finished();
+    /// ```
+    ///
     /// [`Subscriber::on_register_dispatch`]: tracing::Subscriber::on_register_dispatch
     pub fn on_register_dispatch(mut self) -> Self {
         self.expected.push_back(Expect::OnRegisterDispatch);