From 071a678a156dde974d8e470b659c89cb02b07b3b Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Tue, 10 May 2011 00:13:58 +0000
Subject: 	* lib/webrick: Add Documentation

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31499 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 lib/webrick/accesslog.rb | 75 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 72 insertions(+), 3 deletions(-)

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

diff --git a/lib/webrick/accesslog.rb b/lib/webrick/accesslog.rb
index 9a14ae58e5..2b46a805d2 100644
--- a/lib/webrick/accesslog.rb
+++ b/lib/webrick/accesslog.rb
@@ -8,21 +8,90 @@
 # $IPR: accesslog.rb,v 1.1 2002/10/01 17:16:32 gotoyuzo Exp $
 
 module WEBrick
+
+  ##
+  # AccessLog provides logging to various files in various formats.
+  #
+  # Multiple logs may be written to at the same time:
+  #
+  #   access_log = [
+  #     [$stderr, WEBrick::AccessLog::COMMON_LOG_FORMAT],
+  #     [$stderr, WEBrick::AccessLog::REFERER_LOG_FORMAT],
+  #   ]
+  #
+  #   server = WEBrick::HTTPServer.new :AccessLog => access_log
+  #
+  # Custom log formats may be defined.  WEBrick::AccessLog provides a subset
+  # of the formatting from Apache's mod_log_config
+  # http://httpd.apache.org/docs/mod/mod_log_config.html#formats.  See
+  # AccessLog::setup_params for a list of supported options
+
   module AccessLog
+
+    ##
+    # Raised if a parameter such as %e, %i, %o or %n is used without fetching
+    # a specific field.
+
     class AccessLogError < StandardError; end
 
+    ##
+    # The Common Log Format's time format
+
     CLF_TIME_FORMAT     = "[%d/%b/%Y:%H:%M:%S %Z]"
+
+    ##
+    # Common Log Format
+
     COMMON_LOG_FORMAT   = "%h %l %u %t \"%r\" %s %b"
+
+    ##
+    # Short alias for Common Log Format
+
     CLF                 = COMMON_LOG_FORMAT
+
+    ##
+    # Referer Log Format
+
     REFERER_LOG_FORMAT  = "%{Referer}i -> %U"
+
+    ##
+    # User-Agent Log Format
+
     AGENT_LOG_FORMAT    = "%{User-Agent}i"
+
+    ##
+    # Combined Log Format
+
     COMBINED_LOG_FORMAT = "#{CLF} \"%{Referer}i\" \"%{User-agent}i\""
 
     module_function
 
-    # This format specification is a subset of mod_log_config of Apache.
-    #   http://httpd.apache.org/docs/mod/mod_log_config.html#formats
-    def setup_params(config, req, res)
+    # This format specification is a subset of mod_log_config of Apache:
+    #
+    # %a:: Remote IP address
+    # %b:: Total response size
+    # %e{variable}:: Given variable in ENV
+    # %f:: Response filename
+    # %h:: Remote host name
+    # %{header}i:: Given request header
+    # %l:: Remote logname, always "-"
+    # %m:: Request method
+    # %{attr}n:: Given request attribute from <tt>req.attributes</tt>
+    # %{header}o:: Given response header
+    # %p:: Server's request port
+    # %{format}p:: The canonical port of the server serving the request or the
+    #              actual port or the client's actual port.  Valid formats are
+    #              canonical, local or remote.
+    # %q:: Request query string
+    # %r:: First line of the request
+    # %s:: Request status
+    # %t:: Time the request was recieved
+    # %T:: Time taken to process the request
+    # %u:: Remote user from auth
+    # %U:: Unparsed URI
+    # %%:: Literal %
+
+     def setup_params(config, req, res)
       params = Hash.new("")
       params["a"] = req.peeraddr[3]
       params["b"] = res.sent_size
-- 
cgit v1.2.3