From f982fa3bcb861b8bed1c8243483bb03932459899 Mon Sep 17 00:00:00 2001
From: Jonathan Druart <jonathan.druart@biblibre.com>
Date: Thu, 29 Nov 2012 14:02:50 +0100
Subject: [PATCH] Bug 8190: Follow Add some POD

Add POD and prefix private methods with _

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
---
 Koha/Utils/Logger.pm | 161 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 129 insertions(+), 32 deletions(-)

diff --git a/Koha/Utils/Logger.pm b/Koha/Utils/Logger.pm
index e3937fc..e8c0b91 100644
--- a/Koha/Utils/Logger.pm
+++ b/Koha/Utils/Logger.pm
@@ -1,22 +1,5 @@
 package Koha::Utils::Logger;
 
-# Copyright 2012 Biblibre SARL
-#
-# This file is part of Koha.
-#
-# Koha is free software; you can redistribute it and/or modify it under the
-# terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2 of the License, or (at your option) any later
-# version.
-#
-# Koha is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License along
-# with Koha; if not, write to the Free Software Foundation, Inc.,
-# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-
 use Modern::Perl;
 use Log::LogLite;
 
@@ -68,7 +51,7 @@ sub new {
     return bless( $self, $class );
 }
 
-sub write {
+sub _write {
     my ( $self, $msg, $log_level, $dump, $cb ) = @_;
 
     if ( not $self->{LOGGER} ) {
@@ -92,46 +75,46 @@ sub write {
 
 sub unusable {
     my ( $self, $msg, $dump ) = @_;
-    my $cb = $self->called_by();
-    $self->write( $msg, $UNUSABLE_LOG_LEVEL, $dump, $cb );
+    my $cb = $self->_called_by();
+    $self->_write( $msg, $UNUSABLE_LOG_LEVEL, $dump, $cb );
 }
 
 sub critical {
     my ( $self, $msg, $dump ) = @_;
-    my $cb = $self->called_by();
-    $self->write( $msg, $CRITICAL_LOG_LEVEL, $dump, $cb );
+    my $cb = $self->_called_by();
+    $self->_write( $msg, $CRITICAL_LOG_LEVEL, $dump, $cb );
 }
 
 sub error {
     my ( $self, $msg, $dump ) = @_;
-    my $cb = $self->called_by();
-    $self->write( $msg, $ERROR_LOG_LEVEL, $dump, $cb );
+    my $cb = $self->_called_by();
+    $self->_write( $msg, $ERROR_LOG_LEVEL, $dump, $cb );
 }
 
 sub warning {
     my ( $self, $msg, $dump ) = @_;
-    my $cb = $self->called_by();
-    $self->write( $msg, $WARNING_LOG_LEVEL, $dump, $cb );
+    my $cb = $self->_called_by();
+    $self->_write( $msg, $WARNING_LOG_LEVEL, $dump, $cb );
 }
 
 sub log {
     my ( $self, $msg, $dump ) = @_;
-    $self->write( $msg, $NORMAL_LOG_LEVEL, $dump );
+    $self->_write( $msg, $NORMAL_LOG_LEVEL, $dump );
 }
 
 sub normal {
     my ( $self, $msg, $dump ) = @_;
-    $self->write( $msg, $NORMAL_LOG_LEVEL, $dump );
+    $self->_write( $msg, $NORMAL_LOG_LEVEL, $dump );
 }
 
 sub info {
     my ( $self, $msg, $dump ) = @_;
-    $self->write( $msg, $INFO_LOG_LEVEL, $dump );
+    $self->_write( $msg, $INFO_LOG_LEVEL, $dump );
 }
 
 sub debug {
     my ( $self, $msg, $dump ) = @_;
-    $self->write( $msg, $DEBUG_LOG_LEVEL, $dump );
+    $self->_write( $msg, $DEBUG_LOG_LEVEL, $dump );
 }
 
 sub level {
@@ -142,7 +125,7 @@ sub level {
       : ( $self->{LEVEL} = @_ ? shift : $self->{LEVEL} );
 }
 
-sub called_by {
+sub _called_by {
     my $self  = shift;
     my $depth = 2;
     my $args;
@@ -165,7 +148,7 @@ sub called_by {
             last;
         }
         $depth++;
-        $line = (3) ? "$file:" . $line . "-->" : "";
+        $line = "$file:" . $line . "-->";
         push( @subr, $line . $subr );
     }
     @subr = reverse(@subr);
@@ -184,3 +167,117 @@ sub get_messages {
 }
 
 1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+Koha::Utils::Logger - Logging module for Koha
+
+=head1 DESCRIPTION
+
+This module is the logging engine that prints your logs to the koha log file or to stderr.
+
+=head1 USAGE
+
+New instance:
+    my $logger = Koha::Utils::Logger->new(
+        {
+            file  => $my_log_filepath,
+            level => $my_level
+        }
+    );
+
+The default level is 'NORMAL'.
+The default file is the environment variable KOHA_LOG ($ENV{KOHA_LOG}).
+If the previous created instance has the same filename, the previous instance is returned.
+
+If no file is given, the logs are send to stderr.
+
+7 levels are available:
+    DEBUG, INFO, NORMAL, WARN, ERROR, CRIT, UNUS
+
+You can call the 7 log methods with a second parameter (defined and != 0) to dump your message with the Data::Dumper module.
+Useful to display a complex structure.
+
+=head1 METHODS
+
+=head2 new
+
+The constructor method
+
+=head2 _write
+
+private method to write a message.
+Writes the log message to the file or stderr.
+
+=head2 unusable
+
+add a message with an unusable level
+
+=head2 critical
+
+add a message with a critical level
+
+=head2 error
+
+add a message with an error level
+
+=head2 warning
+
+add a message with a warning level
+
+=head2 log
+
+add a message with a normal level
+
+=head2 normal
+
+add a message with a normal level
+
+=head2 info
+
+add a message with an information level
+
+=head2 debug
+
+add a message with a debug level
+
+=head2 level
+
+set or get a level for this instance
+
+=head2 _called_by
+
+This private method returns a callback trace.
+
+=head2 get_messages
+
+Returns all messages for this instance.
+
+=head1 AUTHORS
+
+This module has been written by Jonathan Druart.
+
+=head1 COPYRIGHT
+
+Copyright 2012 Biblibre SARL
+
+=head1 LICENSE
+
+This file is part of Koha.
+
+Koha is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later version.
+
+You should have received a copy of the GNU General Public License along with Koha; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
+Fifth Floor, Boston, MA 02110-1301 USA.
+
+=head1 DISCLAIMER OF WARRANTY
+
+Koha is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+=cut
-- 
2.1.0