Documentation updates

3 files changed, 25 insertions, 13 deletions

diff --git a/lib/rack/common_logger.rb b/lib/rack/common_logger.rb
index 9d8eaefb..5297db7c 100644
--- a/lib/rack/common_logger.rb
+++ b/lib/rack/common_logger.rb
@@ -4,30 +4,35 @@ module Rack
   # 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 either +write+ or +<<+ 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)
+  # to the configured logger.
   class CommonLogger
     # Common Log Format: http://httpd.apache.org/docs/1.3/logs.html#common
     #
     #   lilith.local - - [07/Aug/2006 23:58:02 -0400] "GET / HTTP/1.1" 500 -
     #
     #   %{%s - %s [%s] "%s %s%s %s" %d %s\n} %
+    #
+    # The actual format is slightly different than the above due to the
+    # separation of SCRIPT_NAME and PATH_INFO, and because the elapsed
+    # time in seconds is included at the end.
     FORMAT = %{%s - %s [%s] "%s %s%s%s %s" %d %s %0.4f\n}
 
+    # +logger+ can be any object that supports the +write+ or +<<+ methods,
+    # which includes the standard library Logger.  These methods are called
+    # with a single string argument, the log message.
+    # If +logger+ is nil, CommonLogger will fall back <tt>env['rack.errors']</tt>.
     def initialize(app, logger = nil)
       @app = app
       @logger = logger
     end
 
+    # Log all requests in common_log format after a response has been
+    # returned.  Note that if the app raises an exception, the request
+    # will not be logged, so if exception handling middleware are used,
+    # they should be loaded after this middleware.  Additionally, because
+    # the logging happens after the request body has been fully sent, any
+    # exceptions raised during the sending of the response body will
+    # cause the request not to be logged.
     def call(env)
       began_at = Utils.clock_time
       status, header, body = @app.call(env)
@@ -38,6 +43,7 @@ module Rack
 
     private
 
+    # Log the request to the configured logger.
     def log(env, status, header, began_at)
       length = extract_content_length(header)
 
@@ -64,6 +70,8 @@ module Rack
       end
     end
 
+    # Attempt to determine the content length for the response to
+    # include it in the logged data.
     def extract_content_length(headers)
       value = headers[CONTENT_LENGTH]
       !value || value.to_s == '0' ? '-' : value
diff --git a/lib/rack/content_length.rb b/lib/rack/content_length.rb
index 1acd79a7..da548857 100644
--- a/lib/rack/content_length.rb
+++ b/lib/rack/content_length.rb
@@ -2,7 +2,10 @@
 
 module Rack
 
-  # Sets the Content-Length header on responses with fixed-length bodies.
+  # Sets the Content-Length header on responses that do not specify
+  # a Content-Length or Transfer-Encoding header.  Note that this
+  # does not fix responses that have an invalid Content-Length
+  # header specified.
   class ContentLength
     include Rack::Utils
 
diff --git a/lib/rack/content_type.rb b/lib/rack/content_type.rb
index 4814d200..3640e3a2 100644
--- a/lib/rack/content_type.rb
+++ b/lib/rack/content_type.rb
@@ -7,7 +7,8 @@ module Rack
   # Builder Usage:
   #   use Rack::ContentType, "text/plain"
   #
-  # When no content type argument is provided, "text/html" is assumed.
+  # When no content type argument is provided, "text/html" is the
+  # default.
   class ContentType
     include Rack::Utils