document the new logging infrastructure more accurately

rayon-core/src/log.rs

@@ -1,11 +1,22 @@
 //! Debug Logging
 //!
-//! To use in a debug build, set the env var `RAYON_RS_LOG=1`.  In a
-//! release build, logs are compiled out by default unless Rayon is built
-//! with `--cfg rayon_rs_log` (try `RUSTFLAGS="--cfg rayon_rs_log"`).
+//! To use in a debug build, set the env var `RAYON_RS_LOG` as
+//! described below.  In a release build, logs are compiled out by
+//! default unless Rayon is built with `--cfg rayon_rs_log` (try
+//! `RUSTFLAGS="--cfg rayon_rs_log"`).
 //!
 //! Note that logs are an internally debugging tool and their format
 //! is considered unstable, as are the details of how to enable them.
+//!
+//! # Valid values for RAYON_RS_LOG
+//!
+//! The `RAYON_RS_LOG` variable can take on the following values:
+//!
+//! * `tail:<file>` -- dumps the last 10,000 events into the given file;
+//!   useful for tracking down deadlocks
+//! * `profile:<file>` -- dumps only those events needed to reconstruct how
+//!   many workers are active at a given time
+//! * `all:<file>` -- dumps every event to the file; useful for debugging
 
 use crossbeam_channel::{self, Receiver, Sender};
 use std::collections::VecDeque;