Commit 25607079f0f405d09202378d7435a59a7a96d649 | zig

author	heidezomp <heidezomp@protonmail.com> 2020-08-12 15:37:56+02:00
committer	heidezomp <heidezomp@protonmail.com> 2020-08-12 15:37:56+02:00
log	25607079f0f405d09202378d7435a59a7a96d649
tree	60c44af469e2923e26d1e3bc7e31d66d1beea961
parent	7db2c11537552250462a5f4ab162e5ef4183489c

std.log: add documentation for scoped logging

 * Add short documentation to std.log.scoped and std.log.default
 * Update the module documentation and example to explain the difference
   between using explicit scopes, using a scoped logging namespace, and
   using the default namespace

1 files changed, 18 insertions(+), 1 deletions(-)

lib
- std
  - log.zig

lib/std/log.zig+18-1

 @@ -2,12 +2,16 @@ const std = @import("std.zig");
 const builtin = std.builtin;
 const root = @import("root");
-//! std.log is standardized interface for logging which allows for the logging
+//! std.log is a standardized interface for logging which allows for the logging
 //! 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.
 //!
 //! An example root.log might look something like this:
 //!
 @@ -44,16 +48,26 @@ 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 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 the default namespace:
+//!     // Won't be printed as log_level is .warn
+//!     std.log.default.info("I don't care about my namespace", .{});
 //! }
 //! ```
 //! 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
 //! ```
 pub const Level = enum {
 @@ -201,6 +215,8 @@ pub fn debug(
     log(.debug, scope, format, args);
 }
+/// Returns a scoped logging namespace that logs all messages using the scope
+/// provided here.
 pub fn scoped(comptime scope: @Type(.EnumLiteral)) type {
     return struct {
         /// Log an emergency message to stderr. This log level is intended to be used
 @@ -283,4 +299,5 @@ pub fn scoped(comptime scope: @Type(.EnumLiteral)) type {
     };
 }
+/// The default scoped logging namespace.
 pub const default = scoped(.default);