* lib/cgi.rb: Add toplevel documentation to class CGI

	* lib/cgi/session.rb: Add overview documentation to CGI::Cookie
	* lib/cgi/html.rb:  Don't add CGI::TagMaker documentation to CGI.
	  Patch by David Copeland.  [Ruby 1.9 - Bug ruby#4704]
	* lib/cgi/core.rb:  Clean up CGI documentation.  Patch by David
	  Copeland.  [Ruby 1.9 - Bug ruby#4704]
	* lib/cgi/cookie.rb:  Clean up CGI::Cookie documentation.  Patch by
	  David Copeland.  [Ruby 1.9 - Bug ruby#4704]


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

ChangeLog

@@ -1,3 +1,14 @@
+Tue May 17 06:21:15 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/cgi.rb: Add toplevel documentation to class CGI
+	* lib/cgi/session.rb: Add overview documentation to CGI::Cookie
+	* lib/cgi/html.rb:  Don't add CGI::TagMaker documentation to CGI.
+	  Patch by David Copeland.  [Ruby 1.9 - Bug #4704]
+	* lib/cgi/core.rb:  Clean up CGI documentation.  Patch by David
+	  Copeland.  [Ruby 1.9 - Bug #4704]
+	* lib/cgi/cookie.rb:  Clean up CGI::Cookie documentation.  Patch by
+	  David Copeland.  [Ruby 1.9 - Bug #4704]
+
 Tue May 17 05:52:30 2011  Eric Hodel  <drbrain@segment7.net>
 
 	* ext/digest: Improve documentation of Digest, Digest::HMAC and

lib/cgi.rb

@@ -9,31 +9,25 @@
 #
 # Documentation: Wakou Aoyama (RDoc'd and embellished by William Webber)
 #
+
+raise "Please, use ruby 1.9.0 or later." if RUBY_VERSION < "1.9.0"
+
 # == Overview
 #
-# The Common Gateway Interface (CGI) is a simple protocol
-# for passing an HTTP request from a web server to a
-# standalone program, and returning the output to the web
-# browser.  Basically, a CGI program is called with the
-# parameters of the request passed in either in the
-# environment (GET) or via $stdin (POST), and everything
-# it prints to $stdout is returned to the client.
+# The Common Gateway Interface (CGI) is a simple protocol for passing an HTTP
+# request from a web server to a standalone program, and returning the output
+# to the web browser.  Basically, a CGI program is called with the parameters
+# of the request passed in either in the environment (GET) or via $stdin
+# (POST), and everything it prints to $stdout is returned to the client.
 #
-# This file holds the +CGI+ class.  This class provides
-# functionality for retrieving HTTP request parameters,
-# managing cookies, and generating HTML output.  See the
-# class documentation for more details and examples of use.
+# This file holds the CGI class.  This class provides functionality for
+# retrieving HTTP request parameters, managing cookies, and generating HTML
+# output.
 #
-# The file cgi/session.rb provides session management
-# functionality; see that file for more details.
+# The file CGI::Session provides session management functionality; see that
+# class for more details.
 #
-# See http://www.w3.org/CGI/ for more information on the CGI
-# protocol.
-
-raise "Please, use ruby 1.9.0 or later." if RUBY_VERSION < "1.9.0"
-
-# CGI class.  See documentation for the file cgi.rb for an overview
-# of the CGI protocol.
+# See http://www.w3.org/CGI/ for more information on the CGI protocol.
 #
 # == Introduction
 #
@@ -269,6 +263,10 @@
 #   CGI.new("html4Tr")  # html4.01 Transitional
 #   CGI.new("html4Fr")  # html4.01 Frameset
 #
+
+class CGI
+end
+
 require 'cgi/core'
 require 'cgi/cookie'
 require 'cgi/util'

lib/cgi/cookie.rb

@@ -1,58 +1,66 @@
-# Class representing an HTTP cookie.
-#
-# In addition to its specific fields and methods, a Cookie instance
-# is a delegator to the array of its values.
-#
-# See RFC 2965.
-#
-# == Examples of use
-#   cookie1 = CGI::Cookie::new("name", "value1", "value2", ...)
-#   cookie1 = CGI::Cookie::new("name" => "name", "value" => "value")
-#   cookie1 = CGI::Cookie::new('name'    => 'name',
-#                              'value'   => ['value1', 'value2', ...],
-#                              'path'    => 'path',   # optional
-#                              'domain'  => 'domain', # optional
-#                              'expires' => Time.now, # optional
-#                              'secure'  => true      # optional
-#                             )
-#
-#   cgi.out("cookie" => [cookie1, cookie2]) { "string" }
-#
-#   name    = cookie1.name
-#   values  = cookie1.value
-#   path    = cookie1.path
-#   domain  = cookie1.domain
-#   expires = cookie1.expires
-#   secure  = cookie1.secure
-#
-#   cookie1.name    = 'name'
-#   cookie1.value   = ['value1', 'value2', ...]
-#   cookie1.path    = 'path'
-#   cookie1.domain  = 'domain'
-#   cookie1.expires = Time.now + 30
-#   cookie1.secure  = true
 class CGI
   @@accept_charset="UTF-8" unless defined?(@@accept_charset)
+  # Class representing an HTTP cookie.
+  #
+  # In addition to its specific fields and methods, a Cookie instance
+  # is a delegator to the array of its values.
+  #
+  # See RFC 2965.
+  #
+  # == Examples of use
+  #   cookie1 = CGI::Cookie::new("name", "value1", "value2", ...)
+  #   cookie1 = CGI::Cookie::new("name" => "name", "value" => "value")
+  #   cookie1 = CGI::Cookie::new('name'    => 'name',
+  #                              'value'   => ['value1', 'value2', ...],
+  #                              'path'    => 'path',   # optional
+  #                              'domain'  => 'domain', # optional
+  #                              'expires' => Time.now, # optional
+  #                              'secure'  => true      # optional
+  #                             )
+  #
+  #   cgi.out("cookie" => [cookie1, cookie2]) { "string" }
+  #
+  #   name    = cookie1.name
+  #   values  = cookie1.value
+  #   path    = cookie1.path
+  #   domain  = cookie1.domain
+  #   expires = cookie1.expires
+  #   secure  = cookie1.secure
+  #
+  #   cookie1.name    = 'name'
+  #   cookie1.value   = ['value1', 'value2', ...]
+  #   cookie1.path    = 'path'
+  #   cookie1.domain  = 'domain'
+  #   cookie1.expires = Time.now + 30
+  #   cookie1.secure  = true
   class Cookie < Array
 
     # Create a new CGI::Cookie object.
     #
-    # The contents of the cookie can be specified as a +name+ and one
-    # or more +value+ arguments.  Alternatively, the contents can
-    # be specified as a single hash argument.  The possible keywords of
-    # this hash are as follows:
+    # :call-seq:
+    #   Cookie.new(name_string,*value)
+    #   Cookie.new(options_hash)
     #
-    # name:: the name of the cookie.  Required.
-    # value:: the cookie's value or list of values.
-    # path:: the path for which this cookie applies.  Defaults to the
-    #        base directory of the CGI script.
-    # domain:: the domain for which this cookie applies.
-    # expires:: the time at which this cookie expires, as a +Time+ object.
-    # secure:: whether this cookie is a secure cookie or not (default to
-    #          false).  Secure cookies are only transmitted to HTTPS
-    #          servers.
+    # +name_string+::
+    #   The name of the cookie; in this form, there is no #domain or
+    #   #expiration.  The #path is gleaned from the +SCRIPT_NAME+ environment
+    #   variable, and #secure is false.
+    # <tt>*value</tt>::
+    #   value or list of values of the cookie
+    # +options_hash+::
+    #   A Hash of options to initialize this Cookie.  Possible options are:
     #
-    # These keywords correspond to attributes of the cookie object.
+    #   name:: the name of the cookie.  Required.
+    #   value:: the cookie's value or list of values.
+    #   path:: the path for which this cookie applies.  Defaults to the
+    #          the value of the +SCRIPT_NAME+ environment variable.
+    #   domain:: the domain for which this cookie applies.
+    #   expires:: the time at which this cookie expires, as a +Time+ object.
+    #   secure:: whether this cookie is a secure cookie or not (default to
+    #            false).  Secure cookies are only transmitted to HTTPS
+    #            servers.
+    #
+    #   These keywords correspond to attributes of the cookie object.
     def initialize(name = "", *value)
       @domain = nil
       @expires = nil
@@ -85,7 +93,15 @@ def initialize(name = "", *value)
       super(value)
     end
 
-    attr_accessor("name", "path", "domain", "expires")
+    # Name of this cookie, as a +String+
+    attr_accessor :name
+    # Path for which this cookie applies, as a +String+
+    attr_accessor :path
+    # Domain for which this cookie applies, as a +String+
+    attr_accessor :domain
+    # Time at which this cookie expires, as a +Time+
+    attr_accessor :expires
+    # True if this cookie is secure; false otherwise
     attr_reader("secure")
 
     def value
@@ -117,7 +133,6 @@ def to_s
 
   end # class Cookie
 
-
   # Parse a raw cookie string into a hash of cookie-name=>Cookie
   # pairs.
   #