std.log: update documentation and example for scoped logging

1 files changed, 24 insertions, 22 deletions

diff --git a/lib/std/log.zig b/lib/std/log.zig
index 706851d0be..8d5554aa46 100644
--- a/lib/std/log.zig
+++ b/lib/std/log.zig
@@ -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 {