From a8e5010db81e34cf5192aafd4a2911e4d0e4d8e9 Mon Sep 17 00:00:00 2001
From: Kuba Fietkiewicz <jfietkiewicz@attinteractive.com>
Date: Tue, 24 May 2011 13:28:54 -0700
Subject: [PATCH] Completed CGI documentation

---
 lib/cgi/cookie.rb         |    3 +++
 lib/cgi/core.rb           |   16 +++++++++++++---
 lib/cgi/html.rb           |    3 +++
 lib/cgi/session.rb        |    2 +-
 lib/cgi/session/pstore.rb |    4 ++--
 lib/cgi/util.rb           |   16 ++++++++++------
 6 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/lib/cgi/cookie.rb b/lib/cgi/cookie.rb
index c252693..d52e532 100644
--- a/lib/cgi/cookie.rb
+++ b/lib/cgi/cookie.rb
@@ -1,3 +1,6 @@
+##
+# Cookie methods in the CGI module
+#
 class CGI
   @@accept_charset="UTF-8" unless defined?(@@accept_charset)
   # Class representing an HTTP cookie.
diff --git a/lib/cgi/core.rb b/lib/cgi/core.rb
index a756ab5..f966a3e 100644
--- a/lib/cgi/core.rb
+++ b/lib/cgi/core.rb
@@ -1,7 +1,7 @@
-#--
+##
 # Methods for generating HTML, parsing CGI-related parameters, and
 # generating HTTP responses.
-#++
+#
 class CGI
 
   $CGI_ENV = ENV    # for FCGI support
@@ -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/html.rb b/lib/cgi/html.rb
index 04e2431..0867750 100644
--- a/lib/cgi/html.rb
+++ b/lib/cgi/html.rb
@@ -1,3 +1,6 @@
+##
+# HTML element generating methods
+#
 class CGI
   # Base module for HTML-generation mixins.
   #
diff --git a/lib/cgi/session.rb b/lib/cgi/session.rb
index 42b5ead..61be3e8 100644
--- a/lib/cgi/session.rb
+++ b/lib/cgi/session.rb
@@ -12,7 +12,7 @@
 require 'cgi'
 require 'tmpdir'
 
-class CGI
+class CGI #:nodoc:
 
   # == Overview
   #
diff --git a/lib/cgi/session/pstore.rb b/lib/cgi/session/pstore.rb
index a63d7d3..ed5a794 100644
--- a/lib/cgi/session/pstore.rb
+++ b/lib/cgi/session/pstore.rb
@@ -12,8 +12,8 @@
 require 'cgi/session'
 require 'pstore'
 
-class CGI
-  class Session
+class CGI #:nodoc:
+  class Session #:nodoc:
     # PStore-based session storage class.
     #
     # This builds upon the top-level PStore class provided by the
diff --git a/lib/cgi/util.rb b/lib/cgi/util.rb
index e611cbe..8b9549e 100644
--- a/lib/cgi/util.rb
+++ b/lib/cgi/util.rb
@@ -1,3 +1,6 @@
+##
+# Utility methods for escaping and prettifying HTML, and for date formatting.
+#
 class CGI
   @@accept_charset="UTF-8" unless defined?(@@accept_charset)
   # URL-encode a string.
@@ -20,6 +23,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;',
@@ -84,12 +88,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
@@ -139,12 +143,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
-- 
1.7.2.1