2 files changed, 90 insertions, 46 deletions
diff --git a/src/libstd/logging.rs b/src/libstd/logging.rs
index 27a2af95a2a..5e1ef3658b3 100644
--- a/src/libstd/logging.rs
+++ b/src/libstd/logging.rs
@@ -8,40 +8,101 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Logging
+/*!
 
-use fmt;
-use option::*;
-use os;
-use rt;
-use rt::logging::{Logger, StdErrLogger};
+Logging
 
-/// Turns on logging to stdout globally
-pub fn console_on() {
-    rt::logging::console_on();
-}
+This module is used by the compiler when emitting output for the logging family
+of macros. The methods of this module shouldn't necessarily be used directly,
+but rather through the logging macros defined.
 
-/**
- * Turns off logging to stdout globally
- *
- * Turns off the console unless the user has overridden the
- * runtime environment's logging spec, e.g. by setting
- * the RUST_LOG environment variable
- */
-pub fn console_off() {
-    // If RUST_LOG is set then the console can't be turned off
-    if os::getenv("RUST_LOG").is_some() {
-        return;
-    }
+There are five macros that the logging subsystem uses:
+
+* `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any
+                       related `format!` arguments
+* `debug!(...)` - a macro hard-wired to the log level of 4
+* `info!(...)` - a macro hard-wired to the log level of 3
+* `warn!(...)` - a macro hard-wired to the log level of 2
+* `error!(...)` - a macro hard-wired to the log level of 1
+
+All of these macros use the same style of syntax as the `format!` syntax
+extension. Details about the syntax can be found in the documentation of
+`std::fmt` along with the Rust tutorial/manual
+
+## Enabling logging
+
+Log levels are controlled on a per-module basis, and by default all logging is
+disabled except for `error!` (a log level of 1). Logging is controlled via the
+`RUST_LOG` environment variable. The value of this environment variable is a
+comma-separated list of logging directives. A logging directive is of the form:
+
+```
+path::to::module=log_level
+```
+
+The path to the module is rooted in the name of the crate it was compiled for,
+so if your program is contained in a file `hello.rs`, for example, to turn on
+logging for this file you would use a value of `RUST_LOG=hello`. Furthermore,
+this path is a prefix-search, so all modules nested in the specified module will
+also have logging enabled.
+
+The actual `log_level` is optional to specify. If omitted, all logging will be
+enabled. If specified, the it must be either a numeric in the range of 1-255, or
+it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric
+is specified, then all logging less than or equal to that numeral is enabled.
+For example, if logging level 3 is active, error, warn, and info logs will be
+printed, but debug will be omitted.
+
+As the log level for a module is optional, the module to enable logging for is
+also optional. If only a `log_level` is provided, then the global log level for
+all modules is set to this value.
 
-    rt::logging::console_off();
+Some examples of valid values of `RUST_LOG` are:
+
+```
+hello                // turns on all logging for the 'hello' module
+info                 // turns on all info logging
+hello=debug          // turns on debug logging for 'hello'
+hello=3              // turns on info logging for 'hello'
+hello,std::hashmap   // turns on hello, and std's hashmap logging
+error,hello=warn     // turn on global error logging and also warn for hello
+```
+
+## Performance and Side Effects
+
+Each of these macros will expand to code similar to:
+
+```rust
+if log_level <= my_module_log_level() {
+    ::std::logging::log(log_level, format!(...));
 }
+```
 
-#[allow(missing_doc)]
-pub fn log(_level: u32, args: &fmt::Arguments) {
-    use rt::task::Task;
-    use rt::local::Local;
+What this means is that each of these macros are very cheap at runtime if
+they're turned off (just a load and an integer comparison). This also means that
+if logging is disabled, none of the components of the log will be executed.
+
+## Useful Values
+
+For convenience, if a value of `::help` is set for `RUST_LOG`, a program will
+start, print out all modules registered for logging, and then exit.
 
+*/
+
+use fmt;
+use option::*;
+use rt::local::Local;
+use rt::logging::{Logger, StdErrLogger};
+use rt::task::Task;
+
+/// This function is called directly by the compiler when using the logging
+/// macros. This function does not take into account whether the log level
+/// specified is active or not, it will always log something if this method is
+/// called.
+///
+/// It is not recommended to call this function directly, rather it should be
+/// invoked through the logging family of macros.
+pub fn log(_level: u32, args: &fmt::Arguments) {
     unsafe {
         let optional_task: Option<*mut Task> = Local::try_unsafe_borrow();
         match optional_task {
diff --git a/src/libstd/rt/logging.rs b/src/libstd/rt/logging.rs
index 8b8e2762381..b08e76921d8 100644
--- a/src/libstd/rt/logging.rs
+++ b/src/libstd/rt/logging.rs
@@ -10,7 +10,7 @@
 
 use fmt;
 use from_str::from_str;
-use libc::{uintptr_t, exit};
+use libc::exit;
 use option::{Some, None, Option};
 use rt;
 use rt::util::dumb_println;
@@ -174,9 +174,7 @@ pub struct StdErrLogger;
 
 impl Logger for StdErrLogger {
     fn log(&mut self, args: &fmt::Arguments) {
-        if should_log_console() {
-            fmt::writeln(self as &mut rt::io::Writer, args);
-        }
+        fmt::writeln(self as &mut rt::io::Writer, args);
     }
 }
 
@@ -222,21 +220,6 @@ pub fn init() {
     }
 }
 
-#[fixed_stack_segment] #[inline(never)]
-pub fn console_on() { unsafe { rust_log_console_on() } }
-
-#[fixed_stack_segment] #[inline(never)]
-pub fn console_off() { unsafe { rust_log_console_off() } }
-
-#[fixed_stack_segment] #[inline(never)]
-fn should_log_console() -> bool { unsafe { rust_should_log_console() != 0 } }
-
-extern {
-    fn rust_log_console_on();
-    fn rust_log_console_off();
-    fn rust_should_log_console() -> uintptr_t;
-}
-
 // Tests for parse_logging_spec()
 #[test]
 fn parse_logging_spec_valid() {