* 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

ChangeLog

@@ -1,3 +1,11 @@
+Fri Jun 17 06:11:31 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* 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]
+
 Fri Jun 17 04:48:22 2011  Koichi Sasada  <ko1@atdot.net>
 
 	* thread_pthread.c, thread_pthread.h: remove unused variables.

lib/webrick/httpstatus.rb

@@ -10,30 +10,50 @@
 
 module WEBrick
 
+  ##
+  # This module is used to manager HTTP status codes.
+  #
+  # See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more
+  # information.
   module HTTPStatus
 
+    ##
+    # Root of the HTTP status class hierarchy
     class Status < StandardError
-      def initialize(*args)
+      def initialize(*args) # :nodoc:
         args[0] = AccessLog.escape(args[0]) unless args.empty?
         super(*args)
       end
       class << self
-        attr_reader :code, :reason_phrase
+        attr_reader :code, :reason_phrase # :nodoc:
       end
+      
+      # Returns the HTTP status code
       def code() self::class::code end
+      
+      # Returns the HTTP status description
       def reason_phrase() self::class::reason_phrase end
-      alias to_i code
+      
+      alias to_i code # :nodoc:
     end
+
+    # Root of the HTTP info statuses
     class Info        < Status; end
+    # Root of the HTTP sucess statuses
     class Success     < Status; end
+    # Root of the HTTP redirect statuses
     class Redirect    < Status; end
+    # Root of the HTTP error statuses
     class Error       < Status; end
+    # Root of the HTTP client error statuses
     class ClientError < Error; end
+    # Root of the HTTP server error statuses
     class ServerError < Error; end
 
     class EOFError < StandardError; end
 
-    StatusMessage = {
+    # HTTP status codes and descriptions
+    StatusMessage = { # :nodoc:
       100 => 'Continue',
       101 => 'Switching Protocols',
       200 => 'OK',
@@ -76,8 +96,11 @@ module WEBrick
       505 => 'HTTP Version Not Supported'
     }
 
-    CodeToError = {}
+    # Maps a status code to the corresponding Status class
+    CodeToError = {} # :nodoc:
 
+    # Creates a status or error class for each status code and
+    # populates the CodeToError map.
     StatusMessage.each{|code, message|
       message.freeze
       var_name = message.gsub(/[ \-]/,'_').upcase
@@ -99,28 +122,57 @@ module WEBrick
       CodeToError[code] = err_class
     }
 
+    ##
+    # Returns the description corresponding to the HTTP status +code+
+    #
+    #   WEBrick::HTTPStatus.reason_phrase 404
+    #   => "Not Found"
     def reason_phrase(code)
       StatusMessage[code.to_i]
     end
+
+    ##
+    # Is +code+ an informational status?
     def info?(code)
       code.to_i >= 100 and code.to_i < 200
     end
+    
+    ##
+    # Is +code+ a successful status?
     def success?(code)
       code.to_i >= 200 and code.to_i < 300
     end
+    
+    ##
+    # Is +code+ a redirection status?
     def redirect?(code)
       code.to_i >= 300 and code.to_i < 400
     end
+    
+    ##
+    # Is +code+ an error status?
     def error?(code)
       code.to_i >= 400 and code.to_i < 600
     end
+    
+    ##
+    # Is +code+ a client error status?
     def client_error?(code)
       code.to_i >= 400 and code.to_i < 500
     end
+    
+    ##
+    # Is +code+ a server error status?
     def server_error?(code)
       code.to_i >= 500 and code.to_i < 600
     end
 
+    ##
+    # Returns the status class corresponding to +code+
+    #
+    #   WEBrick::HTTPStatus[302]
+    #   => WEBrick::HTTPStatus::NotFound
+    #
     def self.[](code)
       CodeToError[code]
     end

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