POD

diff --git a/lib/Log/Contextual.pm b/lib/Log/Contextual.pm
index 4f757cd..3b96556 100644 (file)
--- a/lib/Log/Contextual.pm
+++ b/lib/Log/Contextual.pm
@@ -12,10 +12,15 @@ BEGIN { @ISA = qw(Exporter) }
 
 our $Get_Logger;
 
-sub set_logger {
+sub set_logger (&) {
    $Get_Logger = $_[0];
 }
 
+sub with_logger (&$) {
+   local $Get_Logger = $_[1];
+   $_[0]->();
+}
+
 sub log_trace (&) {
    my $log = $Get_Logger->();
    $log->trace($_[0]->())
@@ -52,15 +57,122 @@ sub log_fatal (&) {
       if $log->is_fatal;
 }
 
-sub with_logger (&$) {
-   local $Get_Logger = $_[1];
-   $_[0]->();
-}
-
 1;
 
 __END__
 
+=head1 NAME
+
+Log::Contextual - Super simple logging interface
+
+=head1 SYNOPSIS
+
+ use Log::Contextual;
+
+ my $logger  = WarnLogger->new;
+ my $logger2 = FileLogger->new;
+
+ set_logger { $logger };
+
+ log_debug { "program started" };
+
+ sub foo {
+   with_logger {
+     log_trace { "foo entered" };
+     # ...
+     log_trace { "foo left"    };
+   } $logger2;
+ }
+
+=head1 DESCRIPTION
+
+This module is for simplistic but very extensible logging.
+
+=head1 FUNCTIONS
+
+=head2 set_logger
+
+ my $logger = WarnLogger->new;
+ set_logger { $logger };
+
+Arguments: CodeRef $returning_logger
+
+=head2 with_logger
+
+ my $logger = WarnLogger->new;
+ with_logger {
+    if (1 == 0) {
+       log_fatal { 'Non Logical Universe Detected' };
+    } else {
+       log_info  { 'All is good' };
+    }
+ }, sub { $logger};
+
+Arguments: CodeRef $to_execute, CodeRef $returning_logger
+
+=head2 log_trace
+
+ log_trace { 'entered method foo with args ' join q{,}, @args };
+
+Arguments: CodeRef $returning_message
+
+=head2 log_debug
+
+ log_debug { 'entered method foo' };
+
+Arguments: CodeRef $returning_message
+
+=head2 log_info
+
+ log_info { 'started process foo' };
+
+Arguments: CodeRef $returning_message
+
+=head2 log_warn
+
+ log_warn { 'possible misconfiguration at line 10' };
+
+Arguments: CodeRef $returning_message
+
+=head2 log_error
+
+ log_error { 'non-numeric user input!' };
+
+Arguments: CodeRef $returning_message
+
+=head2 log_fatal
+
+ log_fatal { '1 is never equal to 0!' };
+
+Arguments: CodeRef $returning_message
+
+=head1 SUGARY SYNTAX
+
+This package also provides:
+
+L<Log::Contextual::Sugar> - provides Dlog_$level and DlogS_$level convenience
+functions
+
+=head1 AUTHOR
+
+frew - Arthur Axel "fREW" Schmidt <frioux@gmail.com>
+
+=head1 DESIGNER
+
+mst - Matt S. Trout <mst@shadowcat.co.uk>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2010 the Log::Contextual L</AUTHOR> and L</DESIGNER> as listed
+above.
+
+=head1 LICENSE
+
+This library is free software and may be distributed under the same terms as
+Perl 5 itself.
+
+=cut
+
 .:12:44:33:. <@mst> we have a $Get_Logger global that contains a subref
 .:12:45:11:. <@mst> sub log_debug (&) { my $log = $Get_Logger->(); if ($log->is_debug) {
                     $log->debug($_[0]->()} } }