Commit 2439f67061

@@ -325,7 +325,7 @@ pub fn main() !void {
         represents writing data to a file. When the disk is full, a write to the file will fail.
         However, we typically do not expect writing text to the standard output to fail. To avoid having
         to handle the failure case of printing to standard output, you can use alternate functions: the
-        <code>std.log</code> function for proper logging or the <code>std.debug.print</code> function.
+        functions in <code>std.log</code> for proper logging or the <code>std.debug.print</code> function.
         This documentation will use the latter option to print to standard error (stderr) and silently return
         on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of
         <code>std.debug.print</code>.

@@ -6,12 +6,16 @@ const root = @import("root");
 //! of programs and libraries using this interface to be formatted and filtered
 //! by the implementer of the root.log function.
 //!
-//! The scope parameter should be used to give context to the logging. For
-//! example, a library called 'libfoo' might use .libfoo as its scope.
-//! This parameter can either be passed explicitly to the logging functions
-//! provided here, or a scoped logging namespace can be created
-//! using the `log.scoped` function. If logging scopes are not relevant for
-//! your use case, the `log.default` scope namespace can be used.
+//! Each log message has an associated scope enum, which can be used to give
+//! context to the logging. The logging functions in std.log implicitly use a
+//! scope of .default.
+//!
+//! A logging namespace using a custom scope can be created using the
+//! std.log.scoped function, passing the scope as an argument; the logging
+//! functions in the resulting struct use the provided scope parameter.
+//! For example, a library called 'libfoo' might use
+//! `const log = std.log.scoped(.libfoo);` to use .libfoo as the scope of its
+//! log messages.
 //!
 //! An example root.log might look something like this:
 //!
@@ -29,9 +33,9 @@ const root = @import("root");
 //!     args: anytype,
 //! ) void {
 //!     // Ignore all non-critical logging from sources other than
-//!     // .my_project and .nice_library
+//!     // .my_project, .nice_library and .default
 //!     const scope_prefix = "(" ++ switch (scope) {
-//!         .my_project, .nice_library => @tagName(scope),
+//!         .my_project, .nice_library, .default => @tagName(scope),
 //!         else => if (@enumToInt(level) <= @enumToInt(std.log.Level.crit))
 //!             @tagName(scope)
 //!         else
@@ -48,26 +52,24 @@ const root = @import("root");
 //! }
 //!
 //! pub fn main() void {
-//!     // Using explicit scopes:
-//!     // Won't be printed as log_level is .warn
-//!     std.log.info(.my_project, "Starting up.", .{});
-//!     std.log.err(.nice_library, "Something went very wrong, sorry.", .{});
-//!     // Won't be printed as it gets filtered out by our log function
-//!     std.log.err(.lib_that_logs_too_much, "Added 1 + 1", .{});
+//!     // Using the default scope:
+//!     std.log.info("Just a simple informational log message", .{}); // Won't be printed as log_level is .warn
+//!     std.log.warn("Flux capacitor is starting to overheat", .{});
 //!
-//!     // Using a scoped logging namespace:
-//!     const scoped_log = std.log.scoped(.my_project);
-//!     scoped_log.alert("The scope for this message is implicitly .my_project", .{});
+//!     // Using scoped logging:
+//!     const my_project_log = std.log.scoped(.my_project);
+//!     const nice_library_log = std.log.scoped(.nice_library);
+//!     const verbose_lib_log = std.log.scoped(.verbose_lib);
 //!
-//!     // Using the default namespace:
-//!     // Won't be printed as log_level is .warn
-//!     std.log.default.info("I don't care about my namespace", .{});
+//!     my_project_log.info("Starting up", .{}); // Won't be printed as log_level is .warn
+//!     nice_library_log.err("Something went very wrong, sorry", .{});
+//!     verbose_lib_log.err("Added 1 + 1: {}", .{1 + 1}); // Won't be printed as it gets filtered out by our log function
 //! }
 //! ```
 //! Which produces the following output:
 //! ```
-//! [err] (nice_library): Something went very wrong, sorry.
-//! [alert] (my_project): The scope for this message is implicitly .my_project
+//! [warn] (default): Flux capacitor is starting to overheat
+//! [err] (nice_library): Something went very wrong, sorry
 //! ```
 
 pub const Level = enum {