* 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]


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

1 files changed, 64 insertions, 49 deletions

diff --git a/lib/cgi/cookie.rb b/lib/cgi/cookie.rb
index 97a92efc3a..f05f83e0c9 100644
--- a/lib/cgi/cookie.rb
+++ b/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 @@ class CGI
       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 @@ class CGI
 
   end # class Cookie
 
-
   # Parse a raw cookie string into a hash of cookie-name=>Cookie
   # pairs.
   #