* lib/uri/generic.rb (URI::Generic::userinfo): should support

empty password.  [ruby-core:10290]

* lib/uri/generic.rb (URI::Generic::set_password): password can be
  cleared by nil.  [ruby-core:10290]

* lib/uri/common.rb (escape): regard second string argument as a
  character set properly. [ruby-dev:27692]

* lib/uri: Lovely RDOC patches from mathew (metaATpoboxDOTcom).


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

lib/uri/http.rb

@@ -11,7 +11,12 @@ require 'uri/generic'
 module URI
 
   #
-  # RFC1738 section 3.3.
+  # The syntax of HTTP URIs is defined in RFC1738 section 3.3.
+  #
+  # Note that the Ruby URI library allows HTTP URLs containing usernames and
+  # passwords. This is not legal as per the RFC, but used to be 
+  # supported in Internet Explorer 5 and 6, before the MS04-004 security 
+  # update. See <URL:http://support.microsoft.com/kb/834489>.
   #
   class HTTP < Generic
     DEFAULT_PORT = 80
@@ -27,9 +32,27 @@ module URI
     #
     # == Description
     #
-    # Create a new URI::HTTP object from components of URI::HTTP with
-    # check.  It is scheme, userinfo, host, port, path, query and
-    # fragment. It provided by an Array of a Hash.
+    # Create a new URI::HTTP object from components, with syntax checking.
+    #
+    # The components accepted are userinfo, host, port, path, query and
+    # fragment.
+    #
+    # The components should be provided either as an Array, or as a Hash 
+    # with keys formed by preceding the component names with a colon. 
+    #
+    # If an Array is used, the components must be passed in the order
+    # [userinfo, host, port, path, query, fragment].
+    #
+    # Example:
+    #
+    #     newuri = URI::HTTP.build({:host => 'www.example.com', 
+    #       :path> => '/foo/bar'})
+    #
+    #     newuri = URI::HTTP.build([nil, "www.example.com", nil, "/path", 
+    #       "query", 'fragment'])
+    #
+    # Currently, if passed userinfo components this method generates 
+    # invalid HTTP URIs as per RFC 1738.
     #
     def self.build(args)
       tmp = Util::make_components_hash(self, args)
@@ -39,8 +62,17 @@ module URI
     #
     # == Description
     #
-    # Create a new URI::HTTP object from ``generic'' components with no
-    # check.
+    # Create a new URI::HTTP object from generic URI components as per
+    # RFC 2396. No HTTP-specific syntax checking (as per RFC 1738) is 
+    # performed.
+    #
+    # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+, 
+    # +opaque+, +query+ and +fragment+, in that order.
+    #
+    # Example:
+    #
+    #     uri = URI::HTTP.new(['http', nil, "www.example.com", nil, "/path",
+    #       "query", 'fragment'])
     #
     def initialize(*arg)
       super(*arg)
@@ -49,7 +81,10 @@ module URI
     #
     # == Description
     #
-    # Returns: path + '?' + query
+    # Returns the full path for an HTTP request, as required by Net::HTTP::Get.
+    #
+    # If the URI contains a query, the full path is URI#path + '?' + URI#query.
+    # Otherwise, the path is simply URI#path.
     #
     def request_uri
       r = path_query