From bc0ba6f9c09cf75ce245e95573e06328540c2c5a Mon Sep 17 00:00:00 2001
From: Patrick Spek <p.spek@tyil.nl>
Date: Tue, 21 Apr 2020 14:16:08 +0200
Subject: Add extended documentation

---
 lib/Log.rakumod       | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++
 lib/Log/Level.rakumod | 15 +++++++++
 2 files changed, 99 insertions(+)

diff --git a/lib/Log.rakumod b/lib/Log.rakumod
index e0ecb8d..d6e5b4d 100644
--- a/lib/Log.rakumod
+++ b/lib/Log.rakumod
@@ -35,6 +35,90 @@ multi method add-output (IO::Handle:D $, Int() $ where Log::Level::Emergency ≤
 =VERSION 0.0.0
 =AUTHOR  Patrick Spek <p.spek@tyil.nl>
 
+=head1 Description
+
+The C<Log> module provides a role which I<should> be implemented by a logging
+system. It presents a standardized interface for use around the Raku ecosystem.
+This would allow module developers to add logging statements throughout their
+libraries, and these logs being in the same format as the application using the
+libraries.
+
+=head1 Usage
+
+Usage of the C<Log> module goes through implementations of it, such as
+C<Log::Simple>, C<Log::Colored>, or C<Log::JSON>. The C<Log> role itself only
+helps in ensuring the interfaces are the same, allowing easy replacement of the
+implementation if ever needed in the future.
+
+Whatever imlementation of C<Log> you use, it C<must> be set in the C<$*LOG>
+dynamic variable. This makes it available to all the libraries that are used in
+the program. You C<should> set it as early as possible.
+
+Because it must be using the C<$*LOG> variable, module developers around the
+ecosystem can rely on it for their logging needs. However, not every
+application will implement this, and that needs to be accounted for, too. For
+this, make use of Raku's C<with> flow control statement.
+
+=begin code :lang<raku>
+.notice('This is a log message') with $*LOG;
+=end code
+
+This can be used freely and safely, throughout all modules. Any application
+using that module and implementing C<Log> will immediately be able to reap the
+benefits.
+
+=head2 Implementing a Log class
+
+=begin code :lang<raku>
+use Log;
+
+unit class Log::Custom is Log;
+
+# Implement all required methods
+=end code
+
+=head3 Methods
+
+There are 8 log levels, each with two method calls to invoke them. All of these
+I<must> be implemented.
+
+=item C<multi method emergency (Str:D $) { * }>
+=item C<multi method emergency (Str:D $, *@) { * }>
+=item C<multi method alert (Str:D $) { * }>
+=item C<multi method alert (Str:D $, *@) { * }>
+=item C<multi method critical (Str:D $) { * }>
+=item C<multi method critical (Str:D $, *@) { * }>
+=item C<multi method error (Str:D $) { * }>
+=item C<multi method error (Str:D $, *@) { * }>
+=item C<multi method warning (Str:D $) { * }>
+=item C<multi method warning (Str:D $, *@) { * }>
+=item C<multi method notice (Str:D $) { * }>
+=item C<multi method info (Str:D $) { * }>
+=item C<multi method info (Str:D $, *@) { * }>
+=item C<multi method notice (Str:D $, *@) { * }>
+=item C<multi method debug (Str:D $0 { * }>
+=item C<multi method debug (Str:D $, *@) { * }>
+
+Additionally, the following configuration method I<must> be implemented.
+
+=item C<multi method add-output (IO::Handle:D $, Int() $ where Log::Level::Emergency ≤ * ≤ Log::Level::Debug, Callable $?) { * }>
+
+=head2 Environment variables
+
+This logging standard defines two environment variables to respect.
+
+=defn RAKU_LOG_CLASS
+The C<RAKU_LOG_CLASS> allows a user to override the logging class used by the
+application. This allows programs ran interactively to show more human friendly
+logs, and the same program ran in a cluster to provide formatted logs for
+ingestion into a central logging system, without any code changes required.
+
+=defn RAKU_LOG_LEVEL
+This allows a user to override the log level used by the application. This way,
+by default, a program won't be too spammy with low-level details, but a user
+I<can> enable it if they want to figure out why something isn't working the way
+they expected.
+
 =begin LICENSE
 Copyright © 2020
 
diff --git a/lib/Log/Level.rakumod b/lib/Log/Level.rakumod
index 3c57adf..baeae10 100644
--- a/lib/Log/Level.rakumod
+++ b/lib/Log/Level.rakumod
@@ -19,6 +19,21 @@ enum Log::Level <
 =VERSION 0.0.0
 =AUTHOR  Patrick Spek <p.spek@tyil.nl>
 
+=head1 Description
+
+C<Log::Level> is an C<Enum> to allow for human-readable log levels in your
+code, as opposed to magic numbers that give little insight to people not
+familiar with the levels. The allowed values are:
+
+=item C<Log::Level::Emergency>
+=item C<Log::Level::Alert>
+=item C<Log::Level::Critical>
+=item C<Log::Level::Error>
+=item C<Log::Level::Warning>
+=item C<Log::Level::Notice>
+=item C<Log::Level::Info>
+=item C<Log::Level::Debug>
+
 =begin LICENSE
 Copyright © 2020
 
-- 
cgit v1.1