authorgravatar for heidezomp@protonmail.comheidezomp <heidezomp@protonmail.com> 2020-08-12 15:37:56+02:00
committergravatar for heidezomp@protonmail.comheidezomp <heidezomp@protonmail.com> 2020-08-12 15:37:56+02:00
log25607079f0f405d09202378d7435a59a7a96d649
tree60c44af469e2923e26d1e3bc7e31d66d1beea961
parent7db2c11537552250462a5f4ab162e5ef4183489c

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+18-1
......@@ -2,12 +2,16 @@ const std = @import("std.zig");
22const builtin = std.builtin;
33const root = @import("root");
44
5//! std.log is standardized interface for logging which allows for the logging
5//! std.log is a standardized interface for logging which allows for the logging
66//! of programs and libraries using this interface to be formatted and filtered
77//! by the implementer of the root.log function.
88//!
99//! The scope parameter should be used to give context to the logging. For
1010//! example, a library called 'libfoo' might use .libfoo as its scope.
11//! This parameter can either be passed explicitly to the logging functions
12//! provided here, or a scoped logging namespace can be created
13//! using the `log.scoped` function. If logging scopes are not relevant for
14//! your use case, the `log.default` scope namespace can be used.
1115//!
1216//! An example root.log might look something like this:
1317//!
......@@ -44,16 +48,26 @@ const root = @import("root");
4448//! }
4549//!
4650//! pub fn main() void {
51//! // Using explicit scopes:
4752//! // Won't be printed as log_level is .warn
4853//! std.log.info(.my_project, "Starting up.", .{});
4954//! std.log.err(.nice_library, "Something went very wrong, sorry.", .{});
5055//! // Won't be printed as it gets filtered out by our log function
5156//! std.log.err(.lib_that_logs_too_much, "Added 1 + 1", .{});
57//!
58//! // Using a scoped logging namespace:
59//! const scoped_log = std.log.scoped(.my_project);
60//! scoped_log.alert("The scope for this message is implicitly .my_project", .{});
61//!
62//! // Using the default namespace:
63//! // Won't be printed as log_level is .warn
64//! std.log.default.info("I don't care about my namespace", .{});
5265//! }
5366//! ```
5467//! Which produces the following output:
5568//! ```
5669//! [err] (nice_library): Something went very wrong, sorry.
70//! [alert] (my_project): The scope for this message is implicitly .my_project
5771//! ```
5872
5973pub const Level = enum {
......@@ -201,6 +215,8 @@ pub fn debug(
201215 log(.debug, scope, format, args);
202216}
203217
218/// Returns a scoped logging namespace that logs all messages using the scope
219/// provided here.
204220pub fn scoped(comptime scope: @Type(.EnumLiteral)) type {
205221 return struct {
206222 /// 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 {
283299 };
284300}
285301
302/// The default scoped logging namespace.
286303pub const default = scoped(.default);