* lib/webrick: Add Documentation

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

1 files changed, 47 insertions, 0 deletions

diff --git a/lib/webrick/httpserver.rb b/lib/webrick/httpserver.rb
index 929d856a4a..ddf1ac7404 100644
--- a/lib/webrick/httpserver.rb
+++ b/lib/webrick/httpserver.rb
@@ -19,7 +19,28 @@ require 'webrick/accesslog'
 module WEBrick
   class HTTPServerError < ServerError; end
 
+  ##
+  # An HTTP Server
+
   class HTTPServer < ::WEBrick::GenericServer
+    ##
+    # Creates a new HTTP server according to +config+
+    #
+    # An HTTP server uses the following attributes:
+    #
+    # :AccessLog:: An array of access logs.  See WEBrick::AccessLog
+    # :BindAddress:: Local address for the server to bind to
+    # :DocumentRoot:: Root path to serve files from
+    # :DocumentRootOptions:: Options for the default HTTPServlet::FileHandler
+    # :HTTPVersion:: The HTTP version of this server
+    # :Port:: Port to listen on
+    # :RequestCallback:: Called with a request and response before each
+    #                    request is serviced.
+    # :RequestTimeout:: Maximum time to wait between requests
+    # :ServerAlias:: Array of alternate names for this server for virtual
+    #                hosting
+    # :ServerName:: Name for this server for virtual hosting
+
     def initialize(config={}, default=Config::HTTP)
       super(config, default)
       @http_version = HTTPVersion::convert(@config[:HTTPVersion])
@@ -40,6 +61,9 @@ module WEBrick
       @virtual_hosts = Array.new
     end
 
+    ##
+    # Processes requests on +sock+
+
     def run(sock)
       while true
         res = HTTPResponse.new(@config)
@@ -93,6 +117,9 @@ module WEBrick
       end
     end
 
+    ##
+    # Services +req+ and fills in +res+
+
     def service(req, res)
       if req.unparsed_uri == "*"
         if req.request_method == "OPTIONS"
@@ -115,23 +142,37 @@ module WEBrick
       res["allow"] = "GET,HEAD,POST,OPTIONS"
     end
 
+    ##
+    # Mounts +servlet+ on +dir+ passing +options+ to the servlet at creation
+    # time
+
     def mount(dir, servlet, *options)
       @logger.debug(sprintf("%s is mounted on %s.", servlet.inspect, dir))
       @mount_tab[dir] = [ servlet, options ]
     end
 
+    ##
+    # Mounts +proc+ or +block+ on +dir+ and calls it with a
+    # WEBrick::HTTPRequest and WEBrick::HTTPResponse
+
     def mount_proc(dir, proc=nil, &block)
       proc ||= block
       raise HTTPServerError, "must pass a proc or block" unless proc
       mount(dir, HTTPServlet::ProcHandler.new(proc))
     end
 
+    ##
+    # Unmounts +dir+
+
     def unmount(dir)
       @logger.debug(sprintf("unmount %s.", dir))
       @mount_tab.delete(dir)
     end
     alias umount unmount
 
+    ##
+    # Finds a servlet for +path+
+
     def search_servlet(path)
       script_name, path_info = @mount_tab.scan(path)
       servlet, options = @mount_tab[script_name]
@@ -140,6 +181,9 @@ module WEBrick
       end
     end
 
+    ##
+    # Adds +server+ as a virtual host.
+
     def virtual_host(server)
       @virtual_hosts << server
       @virtual_hosts = @virtual_hosts.sort_by{|s|
@@ -151,6 +195,9 @@ module WEBrick
       }
     end
 
+    ##
+    # Finds the appropriate virtual host to handle +req+
+
     def lookup_server(req)
       @virtual_hosts.find{|s|
         (s[:BindAddress].nil? || req.addr[3] == s[:BindAddress]) &&