lib/rack/commonlogger.rb in rack-1.4.1 vs lib/rack/commonlogger.rb in rack-1.4.2

@@ -1,14 +1,27 @@
 require 'rack/body_proxy'
 
 module Rack
-  # Rack::CommonLogger forwards every request to an +app+ given, and
-  # logs a line in the Apache common log format to the +logger+, or
-  # rack.errors by default.
+  # Rack::CommonLogger forwards every request to the given +app+, and
+  # logs a line in the
+  # {Apache common log format}[http://httpd.apache.org/docs/1.3/logs.html#common]
+  # to the +logger+.
+  #
+  # If +logger+ is nil, CommonLogger will fall back +rack.errors+, which is
+  # an instance of Rack::NullLogger.
+  #
+  # +logger+ can be any class, including the standard library Logger, and is
+  # expected to have a +write+ method, which accepts the CommonLogger::FORMAT.
+  # According to the SPEC, the error stream must also respond to +puts+
+  # (which takes a single argument that responds to +to_s+), and +flush+
+  # (which is called without arguments in order to make the error appear for
+  # sure)
   class CommonLogger
     # Common Log Format: http://httpd.apache.org/docs/1.3/logs.html#common
-    # lilith.local - - [07/Aug/2006 23:58:02] "GET / HTTP/1.1" 500 -
-    #             %{%s - %s [%s] "%s %s%s %s" %d %s\n} %
+    #
+    #   lilith.local - - [07/Aug/2006 23:58:02] "GET / HTTP/1.1" 500 -
+    #
+    #   %{%s - %s [%s] "%s %s%s %s" %d %s\n} %
     FORMAT = %{%s - %s [%s] "%s %s%s %s" %d %s %0.4f\n}
 
     def initialize(app, logger=nil)
       @app = app
       @logger = logger