From be3911733043df19c9f57609a055f1a826d496f0 Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Thu, 16 Jun 2011 21:12:00 +0000
Subject: 	* lib/webrick/log.rb:  Improve documentation of BasicLog and
 Log. 	  Patch by Olivier Brisse.  [Ruby 1.9 - Bug #4833] 	*
 lib/webrick/httpstatus.rb:  Improve documentation of 	  WEBrick::HTTPStatus.
  Patch by Olivier Brisse. 	  [Ruby 1.9 - Bug #4833]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32137 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 lib/webrick/log.rb | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

(limited to 'lib/webrick/log.rb')

diff --git a/lib/webrick/log.rb b/lib/webrick/log.rb
index fe253e51a2..546e52700b 100644
--- a/lib/webrick/log.rb
+++ b/lib/webrick/log.rb
@@ -14,9 +14,10 @@ module WEBrick
   # A generic logging class
 
   class BasicLog
-    # log-level constant
+    # log-level constants
     FATAL, ERROR, WARN, INFO, DEBUG = 1, 2, 3, 4, 5
 
+    # log-level, messages above this level will be logged
     attr_accessor :level
 
     ##
@@ -40,11 +41,17 @@ module WEBrick
       end
     end
 
+    ##
+    # Closes the logger (also closes the log device associated to the logger)
     def close
       @log.close if @opened
       @log = nil
     end
 
+    ##
+    # Logs +data+ at +level+ if the given level is above the current log
+    # level.
+
     def log(level, data)
       if @log && level <= @level
         data += "\n" if /\n\Z/ !~ data
@@ -52,24 +59,43 @@ module WEBrick
       end
     end
 
+    ##
+    # Synonym for log(INFO, obj.to_s)
     def <<(obj)
       log(INFO, obj.to_s)
     end
 
+    # Shortcut for logging a FATAL message
     def fatal(msg) log(FATAL, "FATAL " << format(msg)); end
+    # Shortcut for logging an ERROR message
     def error(msg) log(ERROR, "ERROR " << format(msg)); end
+    # Shortcut for logging a WARN message
     def warn(msg)  log(WARN,  "WARN  " << format(msg)); end
+    # Shortcut for logging an INFO message
     def info(msg)  log(INFO,  "INFO  " << format(msg)); end
+    # Shortcut for logging a DEBUG message
     def debug(msg) log(DEBUG, "DEBUG " << format(msg)); end
 
+    # Will the logger output FATAL messages?
     def fatal?; @level >= FATAL; end
+    # Will the logger output ERROR messages?
     def error?; @level >= ERROR; end
+    # Will the logger output WARN messages?
     def warn?;  @level >= WARN; end
+    # Will the logger output INFO messages?
     def info?;  @level >= INFO; end
+    # Will the logger output DEBUG messages?
     def debug?; @level >= DEBUG; end
 
     private
 
+    ##
+    # Formats +arg+ for the logger
+    #
+    # * If +arg+ is an Exception, it will format the error message and
+    #   the back trace.
+    # * If +arg+ responds to #to_str, it will return it.
+    # * Otherwise it will return +arg+.inspect.
     def format(arg)
       if arg.is_a?(Exception)
         "#{arg.class}: #{arg.message}\n\t" <<
@@ -83,16 +109,24 @@ module WEBrick
   end
 
   ##
-  # A logging class with timestamps
+  # A logging class that prepends a timestamp to each message.
 
   class Log < BasicLog
+    # Format of the timestamp which is applied to each logged line.  The
+    # default is <tt>"[%Y-%m-%d %H:%M:%S]"</tt>
     attr_accessor :time_format
 
+    ##
+    # Same as BasicLog#initialize
+    #
+    # You can set the timestamp format through #time_format
     def initialize(log_file=nil, level=nil)
       super(log_file, level)
       @time_format = "[%Y-%m-%d %H:%M:%S]"
     end
 
+    ##
+    # Same as BasicLog#log
     def log(level, data)
       tmp = Time.now.strftime(@time_format)
       tmp << " " << data
-- 
cgit v1.2.3