subscriber: add example of Option<Layer>

[davidbarsky]

This PR contains two changes:

1. An example as how to use Option<Layer> to toggle layers at runtime, and...
2. A fix to an example writing to disk when doc tests are run.

[hawkw]

thanks, this should definitely be featured more prominently in the docs. I had some suggestions, let me know what you think?

[hawkw]

nit: let's put whitespace here

Suggested change

	//! use std::{fs::File, sync::Arc};
	//! let stdout_log = tracing_subscriber::fmt::layer()
	//! use std::{fs::File, sync::Arc};
	//!
	//! let stdout_log = tracing_subscriber::fmt::layer()

[hawkw]

also, it might be worth adding comments to these so the reader knows what they're doing

Suggested change

	//! use std::{fs::File, sync::Arc};
	//! let stdout_log = tracing_subscriber::fmt::layer()
	//! use std::{fs::File, sync::Arc};
	//!
	//! // Always log to stdout in a human-readable format.
	//! let stdout_log = tracing_subscriber::fmt::layer()

[hawkw]

some copyedits --- how about something like

Suggested change

	//! Conditionally enabling/disabling layers at runtime can be challenging due to the generics
	//! used Layers implementations. However, A Layer wrapped in an `Option` is also Layers, which
	//! allows some runtime configuration:
	//! In some cases, a particular [`Layer`] may be enabled or disabled based on
	//! runtime configuration. This can introduce challenges, because the type of a
	//! layered [`Subscriber`] depends on which layers are added to it: if an `if`
	//! or `match` expression adds some [`Layer`]s in one branch and other layers
	//! in another, the [`Subscriber`] values returned by those branches will have
	//! different types.
	//!
	//! However, a [`Layer`] wrapped in an [`Option`] [also implements the `Layer
	//! trait][option-impl]. This allows individual layers to be enabled or disabled at
	//! runtime while always producing a [`Subscriber`] of the same type. For
	//! example:
	//!
	//! [option-impl]: crate::layer::Layer#impl-Layer<S>-for-Option<L>

[hawkw]

also, i think it might be nice to introduce these problems with a compile_fail example that shows code that doesn't work because of creating subscribers of two different types...but it's up to you if you want to spend time on that...

[davidbarsky]

yeah, those copy edits are way better. sorry, when i wrote this, i felt myself fading terribly, and this much better.

I'll also add a compile_fail example.

[hawkw]

@davidbarsky mind if i just go ahead and apply my docs suggestions, or are you still working on this?

[hawkw]

example change looks great, thanks! i commented on a few minor nits

[hawkw]

nit/tioli: this could maybe be simplified to avoid having to import PathBuf

Suggested change

	//! # use std::path::PathBuf;
	//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
	//! # struct Config {
	//! # is_prod: bool,
	//! # path: PathBuf,
	//! # }
	//! # let cfg = Config { is_prod: false, path: PathBuf::from("debug.log") };
	//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
	//! # struct Config {
	//! # is_prod: bool,
	//! # path: &'static str,
	//! # }
	//! # let cfg = Config { is_prod: false, path: "debug.log" };

[hawkw]

i'm not sure if it's really important to add the note about tracing-appender...i wouldn't say it's a hard and fast rule that that crate should always be used when logging to a file, if the user doesn't intend to do things like rotating the log file. not a blocker, though....

[hawkw]

okay, looks great to me! thanks for adding this (and for putting up with all my nitpicks!)