docs: update Compact formatter docs (#1926)

## Motivation

Currently, the RustDoc for the `format::Compact` formatter in
`tracing-subscriber` describes the output from the `master` (v0.2.x)
version of the formatter, not the version on the v0.1.x branch.

## Solution

This PR updates the documentation to describe the actual output format.
Also, I added an example of the formatter in the `examples` directory.

Closes #1909

examples/README.md

@@ -16,24 +16,31 @@ This directory contains a collection of examples that demonstrate the use of the
     Fibonacci numbers, to demonstrate how the `#[instrument]` attribute can
     record function arguments.
 - **tracing-subscriber**:
-  + `fmt`: Demonstrates the use of the `fmt` module in `tracing-subscriber`,
+  + `fmt`: Demonstrates the use of the [`fmt`] module in `tracing-subscriber`,
     which provides a subscriber implementation that logs traces to the console.
+    This example uses the default formatter ([`format::Full`]).
   + `fmt-stderr`: Demonstrates overriding the output stream used by the `fmt`
     subscriber.
-  + `fmt-custom-field`: Demonstrates overriding how the `fmt` subscriber formats
+  + `fmt-pretty`: Demonstrates the output of the [`format::Pretty`] formatter in
+    [`tracing-subscriber::fmt`][`fmt`].
+  + `fmt-compact`: Demonstrates the output of the [`format::Compact`] formatter in
+    [`tracing-subscriber::fmt`][`fmt`].
+  + `fmt-json`: Demonstrates the output of the [`format::Json`] formatter in
+    [`tracing-subscriber::fmt`][`fmt`].
+  + `fmt-custom-field`: Demonstrates overriding how the [`fmt`] subscriber formats
     fields on spans and events.
-  + `fmt-custom-event`: Demonstrates overriding how the `fmt` subscriber formats
+  + `fmt-custom-event`: Demonstrates overriding how the [`fmt`] subscriber formats
     events.
-  + `fmt-multiple-writers.rs`: demonstrates how `fmt::Layer` can write
+  + `fmt-multiple-writers`: demonstrates how [`fmt::Layer`] can write
     to multiple destinations (in this instance, stdout and a file) simultaneously.
-  + `fmt-source-locations.rs`: demonstrates displaying source code locations
-    with `fmt::Layer`.
+  + `fmt-source-locations`: demonstrates displaying source code locations
+    with [`fmt::Layer`].
   + `subscriber-filter`: Demonstrates the `tracing-subscriber::filter` module,
     which provides a layer which adds configurable filtering to a subscriber
     implementation.
   + `tower-load`: Demonstrates how dynamically reloadable filters can be used to
     debug a server under load in production.
-  + `journald`: Demonstrates how to use `fmt` and `journald` layers to output to
+  + `journald`: Demonstrates how to use [`fmt`] and `journald` layers to output to
     both the terminal and the system journal.
   + `toggle-layers` : Demonstrates how Layers can be wrapped with an `Option` allowing
     them to be dynamically toggled.
@@ -75,3 +82,9 @@ This directory contains a collection of examples that demonstrate the use of the
 [tasks]: (https://docs.rs/tokio/0.2.21/tokio/task/index.html)
 [tokio-proxy]: https://github.com/tokio-rs/tokio/blob/v0.1.x/tokio/examples/proxy.rs
 [echo]: https://github.com/hyperium/hyper/blob/0.12.x/examples/echo.rs
+[`fmt`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/index.html
+[`format::Full`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Full.html
+[`format::Pretty`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Pretty.html
+[`format::Compact`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Compact.html
+[`format::Json`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Json.html
+[`fmt::Layer`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Layer.html

examples/examples/fmt-compact.rs

@@ -0,0 +1,22 @@
+#![deny(rust_2018_idioms)]
+#[path = "fmt/yak_shave.rs"]
+mod yak_shave;
+
+fn main() {
+    tracing_subscriber::fmt()
+        .compact()
+        // enable everything
+        .with_max_level(tracing::Level::TRACE)
+        // sets this to be the default, global collector for this application.
+        .init();
+
+    let number_of_yaks = 3;
+    // this creates a new event, outside of any spans.
+    tracing::info!(number_of_yaks, "preparing to shave yaks");
+
+    let number_shaved = yak_shave::shave_all(number_of_yaks);
+    tracing::info!(
+        all_yaks_shaved = number_shaved == number_of_yaks,
+        "yak shaving completed"
+    );
+}

tracing-subscriber/src/fmt/format/mod.rs

@@ -297,12 +297,11 @@ pub struct FieldFnVisitor<'a, F> {
     writer: Writer<'a>,
     result: fmt::Result,
 }
-/// Marker for `Format` that indicates that the compact log format should be used.
+/// Marker for [`Format`] that indicates that the compact log format should be used.
 ///
 /// The compact format includes fields from all currently entered spans, after
-/// the event's fields. Span fields are not grouped by span, and span names are
-/// not shown. In addition, a more compact representation of each event's
-/// [`Level`](tracing::Level) is used.
+/// the event's fields. Span names are listed in order before fields are
+/// displayed.
 #[derive(Default, Debug, Copy, Clone, Eq, PartialEq)]
 pub struct Compact;