* lib/webrick/accesslog.rb: Improved WEBrick documentation.

* lib/webrick/cgi.rb:  ditto.
* lib/webrick/config.rb:  ditto.
* lib/webrick/cookie.rb:  ditto.
* lib/webrick/httpauth/authenticator.rb:  ditto.
* lib/webrick/httpauth/basicauth.rb:  ditto.
* lib/webrick/httpauth/digestauth.rb:  ditto.
* lib/webrick/httpproxy.rb:  ditto.
* lib/webrick/httprequest.rb:  ditto.
* lib/webrick/httpresponse.rb:  ditto.
* lib/webrick/https.rb:  ditto.
* lib/webrick/httpserver.rb:  ditto.
* lib/webrick/httpservlet/cgihandler.rb:  ditto.
* lib/webrick/httpservlet/filehandler.rb:  ditto.
* lib/webrick/httpservlet/prochandler.rb:  ditto.
* lib/webrick/httputils.rb:  ditto.
* lib/webrick/httpversion.rb:  ditto.
* lib/webrick/log.rb:  ditto.
* lib/webrick/server.rb:  ditto.
* lib/webrick/ssl.rb:  ditto.
* lib/webrick/utils.rb:  ditto.
* lib/webrick/version.rb:  ditto.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38945 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

3 files changed, 61 insertions, 17 deletions

diff --git a/lib/webrick/httpservlet/cgihandler.rb b/lib/webrick/httpservlet/cgihandler.rb
index 1976ae6948..7c012ca64b 100644
--- a/lib/webrick/httpservlet/cgihandler.rb
+++ b/lib/webrick/httpservlet/cgihandler.rb
@@ -16,9 +16,20 @@ require 'webrick/httpservlet/abstract'
 module WEBrick
   module HTTPServlet
 
+    ##
+    # Servlet for handling CGI scripts
+    #
+    # Example:
+    #
+    #  server.mount('/cgi/my_script', WEBrick::HTTPServlet::CGIHandler,
+    #               '/path/to/my_script')
+
     class CGIHandler < AbstractServlet
-      Ruby = RbConfig.ruby
-      CGIRunner = "\"#{Ruby}\" \"#{WEBrick::Config::LIBDIR}/httpservlet/cgi_runner.rb\""
+      Ruby = RbConfig.ruby # :nodoc:
+      CGIRunner = "\"#{Ruby}\" \"#{WEBrick::Config::LIBDIR}/httpservlet/cgi_runner.rb\"" # :nodoc:
+
+      ##
+      # Creates a new CGI script servlet for the script at +name+
 
       def initialize(server, name)
         super(server, name)
@@ -27,6 +38,8 @@ module WEBrick
         @cgicmd = "#{CGIRunner} #{server[:CGIInterpreter]}"
       end
 
+      # :stopdoc:
+
       def do_GET(req, res)
         data = nil
         status = -1
@@ -102,6 +115,8 @@ module WEBrick
         res.body = body
       end
       alias do_POST do_GET
+
+      # :startdoc:
     end
 
   end
diff --git a/lib/webrick/httpservlet/filehandler.rb b/lib/webrick/httpservlet/filehandler.rb
index 8736f5773a..d8c66dfdc3 100644
--- a/lib/webrick/httpservlet/filehandler.rb
+++ b/lib/webrick/httpservlet/filehandler.rb
@@ -18,12 +18,29 @@ require 'webrick/httpstatus'
 module WEBrick
   module HTTPServlet
 
+    ##
+    # Servlet for serving a single file.  You probably want to use the
+    # FileHandler servlet instead as it handles directories and fancy indexes.
+    #
+    # Example:
+    #
+    #   server.mount('/my_page.txt', WEBrick::HTTPServlet::DefaultFileHandler,
+    #                '/path/to/my_page.txt')
+    #
+    # This servlet handles If-Modified-Since and Range requests.
+
     class DefaultFileHandler < AbstractServlet
+
+      ##
+      # Creates a DefaultFileHandler instance for the file at +local_path+.
+
       def initialize(server, local_path)
         super(server, local_path)
         @local_path = local_path
       end
 
+      # :stopdoc:
+
       def do_GET(req, res)
         st = File::stat(@local_path)
         mtime = st.mtime
@@ -123,13 +140,20 @@ module WEBrick
         last = filesize - 1 if last >= filesize
         return first, last
       end
+
+      # :startdoc:
     end
 
     ##
-    # Serves files from a directory
+    # Serves a directory including fancy indexing and a variety of other
+    # options.
+    #
+    # Example:
+    #
+    #   server.mount '/assets', WEBrick::FileHandler, '/path/to/assets'
 
     class FileHandler < AbstractServlet
-      HandlerTable = Hash.new
+      HandlerTable = Hash.new # :nodoc:
 
       ##
       # Allow custom handling of requests for files with +suffix+ by class
@@ -150,19 +174,8 @@ module WEBrick
       # Creates a FileHandler servlet on +server+ that serves files starting
       # at directory +root+
       #
-      # If +options+ is a Hash the following keys are allowed:
-      #
-      # :AcceptableLanguages:: Array of languages allowed for accept-language
-      # :DirectoryCallback:: Allows preprocessing of directory requests
-      # :FancyIndexing:: If true, show an index for directories
-      # :FileCallback:: Allows preprocessing of file requests
-      # :HandlerCallback:: Allows preprocessing of requests
-      # :HandlerTable:: Maps file suffixes to file handlers.
-      #                 DefaultFileHandler is used by default but any servlet
-      #                 can be used.
-      # :NondisclosureName:: Do not show files matching this array of globs
-      # :UserDir:: Directory inside ~user to serve content from for /~user
-      #            requests.  Only works if mounted on /
+      # +options+ may be a Hash containing keys from
+      # WEBrick::Config::FileHandler or +true+ or +false+.
       #
       # If +options+ is true or false then +:FancyIndexing+ is enabled or
       # disabled respectively.
@@ -177,6 +190,8 @@ module WEBrick
         @options = default.dup.update(options)
       end
 
+      # :stopdoc:
+
       def service(req, res)
         # if this class is mounted on "/" and /~username is requested.
         # we're going to override path informations before invoking service.
@@ -465,6 +480,7 @@ module WEBrick
         _end_of_html_
       end
 
+      # :startdoc:
     end
   end
 end
diff --git a/lib/webrick/httpservlet/prochandler.rb b/lib/webrick/httpservlet/prochandler.rb
index 2be3c854c1..2f5aa66f45 100644
--- a/lib/webrick/httpservlet/prochandler.rb
+++ b/lib/webrick/httpservlet/prochandler.rb
@@ -13,7 +13,19 @@ require 'webrick/httpservlet/abstract.rb'
 module WEBrick
   module HTTPServlet
 
+    ##
+    # Mounts a proc at a path that accepts a request and response.
+    #
+    # Instead of mounting this servlet with WEBrick::HTTPServer#mount use
+    # WEBrick::HTTPServer#mount_proc:
+    #
+    #   server.mount_proc '/' do |req, res|
+    #     res.body = 'it worked!'
+    #     res.status = 200
+    #   end
+
     class ProcHandler < AbstractServlet
+      # :stopdoc:
       def get_instance(server, *options)
         self
       end
@@ -27,6 +39,7 @@ module WEBrick
       end
 
       alias do_POST do_GET
+      # :startdoc:
     end
 
   end