From b8f3f2d62e62fa8ebfd4e59656173813ec96672a Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Wed, 1 Jun 2011 00:42:06 +0000
Subject: [PATCH] 	* lib/cgi/util.rb:  Improve documentation.  Patch by
 Kuba Fietkiewicz. 	  [Ruby 1.9 - Bug #4775] 	* lib/cgi/core.rb: 
 ditto

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31882 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog       |  6 ++++++
 lib/cgi/core.rb | 12 +++++++++++-
 lib/cgi/util.rb | 16 +++++++---------
 3 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8069d0809a..2a835cc37a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Wed Jun  1 09:41:14 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/cgi/util.rb:  Improve documentation.  Patch by Kuba Fietkiewicz.
+	  [Ruby 1.9 - Bug #4775]
+	* lib/cgi/core.rb:  ditto
+
 Wed Jun  1 09:26:05 2011  Eric Hodel  <drbrain@segment7.net>
 
 	* lib/mathn.rb:  Improve documentation and attach it to Numeric.
diff --git a/lib/cgi/core.rb b/lib/cgi/core.rb
index a756ab5542..5759fd44bd 100644
--- a/lib/cgi/core.rb
+++ b/lib/cgi/core.rb
@@ -17,6 +17,7 @@ class CGI
 
   REVISION = '$Id$' #:nodoc:
 
+  # Whether processing will be required in binary vs text
   NEEDS_BINMODE = File::BINARY != 0
 
   # Path separators in different environments.
@@ -450,6 +451,15 @@ class CGI
       @params.update(hash)
     end
 
+    ##
+    # Parses multipart form elements according to 
+    #   http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2
+    #
+    # Returns a hash of multipart form parameters with bodies of type StringIO or 
+    # Tempfile depending on whether the multipart form element exceeds 10 KB
+    #
+    #   params[name => body]
+    #
     def read_multipart(boundary, content_length)
       ## read first boundary
       stdin = $stdin
@@ -655,6 +665,7 @@ class CGI
     end
     private :initialize_query
 
+    # Returns whether the form contained multipart/form-data
     def multipart?
       @multipart
     end
@@ -705,7 +716,6 @@ class CGI
   #
   #   CGI.accept_charset = "EUC-JP"
   #
-
   @@accept_charset="UTF-8"
 
   # Return the accept character set for all new CGI instances.
diff --git a/lib/cgi/util.rb b/lib/cgi/util.rb
index e611cbedb2..2bb3b0da78 100644
--- a/lib/cgi/util.rb
+++ b/lib/cgi/util.rb
@@ -9,7 +9,6 @@ class CGI
     end.tr(' ', '+')
   end
 
-
   # URL-decode a string with encoding(optional).
   #   string = CGI::unescape("%27Stop%21%27+said+Fred")
   #      # => "'Stop!' said Fred"
@@ -20,6 +19,7 @@ class CGI
     str.valid_encoding? ? str : str.force_encoding(string.encoding)
   end
 
+  # The set of special characters and their escaped values
   TABLE_FOR_ESCAPE_HTML__ = {
     '&' => '&amp;',
     '"' => '&quot;',
@@ -34,7 +34,6 @@ class CGI
     string.gsub(/[&\"<>]/, TABLE_FOR_ESCAPE_HTML__)
   end
 
-
   # Unescape a string that has been HTML-escaped
   #   CGI::unescapeHTML("Usage: foo &quot;bar&quot; &lt;baz&gt;")
   #      # => "Usage: foo \"bar\" <baz>"
@@ -84,12 +83,12 @@ class CGI
     end
   end
 
-  # Synonym for CGI.escapeHTML.
+  # Synonym for CGI::escapeHTML(str)
   def CGI::escape_html(str)
     escapeHTML(str)
   end
-
-  # Synonym for CGI.unescapeHTML.
+  
+  # Synonym for CGI::unescapeHTML(str)
   def CGI::unescape_html(str)
     unescapeHTML(str)
   end
@@ -118,7 +117,6 @@ class CGI
     end
   end
 
-
   # Undo escaping such as that done by CGI::escapeElement()
   #
   #   print CGI::unescapeElement(
@@ -139,12 +137,12 @@ class CGI
     end
   end
 
-  # Synonym for CGI.escapeElement.
+  # Synonym for CGI::escapeElement(str)
   def CGI::escape_element(str)
     escapeElement(str)
   end
-
-  # Synonym for CGI.unescapeElement.
+  
+  # Synonym for CGI::unescapeElement(str)
   def CGI::unescape_element(str)
     unescapeElement(str)
   end