Lovely RDOC patches from mathew (metaATpoboxDOTcom) on URI/* and getoptlong.rb

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

7 files changed, 171 insertions, 40 deletions

diff --git a/lib/.document b/lib/.document
index b7180b5c7b..f917e02070 100644
--- a/lib/.document
+++ b/lib/.document
@@ -6,14 +6,14 @@
 
 # But for now
 
+English.rb
 abbrev.rb
 base64.rb
 benchmark.rb
-cgi.rb
 cgi
+cgi.rb
 complex.rb
 date.rb
-English.rb
 fileutils.rb
 find.rb
 generator.rb
@@ -32,4 +32,5 @@ test/unit.rb
 thread.rb
 thwait.rb
 time.rb
+uri
 yaml.rb
diff --git a/lib/getoptlong.rb b/lib/getoptlong.rb
index 59a5104fc7..6e23cb6c7f 100644
--- a/lib/getoptlong.rb
+++ b/lib/getoptlong.rb
@@ -40,7 +40,13 @@ class GetoptLong
   class InvalidOption    < Error; end
 
   #
-  # Initializer.
+  # The arguments are passed to new() as an array of arrays. Each
+  # subarray has a number of option names which carry the same
+  # meaning, and a ARGUMENT_FLAG, being one of
+  # GetoptLong::NO_ARGUMENT, GetoptLong::REQUIRED_ARGUMENT or
+  # GetoptLong::OPTIONAL_ARGUMENT.  These determine whether the
+  # option takes an argument or not, or whether it is optional The
+  # actual processing is done later with #each().
   #
   def initialize(*arguments)
     #
@@ -103,7 +109,11 @@ class GetoptLong
   end
 
   #
-  # Set ordering.
+  # Set the handling of the ordering of options.  The supplied
+  # argument ordering must be a member of ORDERINGS, i.e one of
+  # GetoptLong::REQUIRE_ORDER, GetoptLong::PERMUTE,
+  # GetoptLong::RETURN_IN_ORDER.  A RuntimeError is raised if
+  # option processin has already started.
   #
   def ordering=(ordering)
     #
@@ -250,7 +260,7 @@ class GetoptLong
   end
 
   #
-  # Set an error (protected).
+  # Set an error (a protected method).
   #
   def set_error(type, message)
     $deferr.print("#{$0}: #{message}\n") if !@quiet
@@ -285,6 +295,8 @@ class GetoptLong
 
   #
   # Get next option name and its argument as an array.
+  # Return nil if the processing is complete (as determined by
+  # STATUS_TERMINATED).
   #
   def get
     option_name, option_argument = nil, ''
@@ -451,7 +463,8 @@ class GetoptLong
   alias get_option get
 
   #
-  # Iterator version of `get'.
+  # Iterator version of `get', passes the option and the
+  # corresponding argument to the supplied block for processing.
   #
   def each
     loop do
diff --git a/lib/uri/ftp.rb b/lib/uri/ftp.rb
index 26109e4d27..3afdce01b4 100644
--- a/lib/uri/ftp.rb
+++ b/lib/uri/ftp.rb
@@ -11,7 +11,7 @@ require 'uri/generic'
 module URI
 
   #
-  # RFC1738 section 3.2.
+  # FTP URI syntax is defined by RFC1738 section 3.2.
   #
   class FTP < Generic
     DEFAULT_PORT = 21
@@ -22,12 +22,11 @@ module URI
       :path, :typecode
     ].freeze
     #
-    # Typecode is, "a", "i" or "d". 
-    # As for "a" the text, as for "i" binary, 
-    # as for "d" the directory is displayed. 
-    # "A" with the text, as for "i" being binary, 
-    # is because the respective data type was called ASCII and 
-    # IMAGE with the protocol of FTP.
+    # Typecode is "a", "i" or "d". 
+    #
+    # * "a" indicates a text file (the FTP command was ASCII)
+    # * "i" indicates a binary file (FTP command IMAGE)
+    # * "d" indicates the contents of a directory should be displayed
     #
     TYPECODE = ['a', 'i', 'd'].freeze
     TYPECODE_PREFIX = ';type='.freeze
@@ -52,11 +51,43 @@ module URI
     #
     # == Description
     #
-    # Creates a new URI::FTP object from components of URI::FTP with
-    # check.  It is scheme, userinfo, host, port, path and typecode. It
-    # provided by an Array or a Hash. typecode is "a", "i" or "d".
+    # Creates a new URI::FTP object from components, with syntax checking.  
+    #
+    # The components accepted are +userinfo+, +host+, +port+, +path+ and 
+    # +typecode+.
+    #
+    # 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, typecode]
+    #
+    # If the path supplied is absolute, it will be escaped in order to
+    # make it absolute in the URI. Examples:
+    #
+    #     require 'uri'
+    #
+    #     uri = URI::FTP.build(['user:password', 'ftp.example.com', nil, 
+    #       '/path/file.> zip', 'i'])
+    #     puts uri.to_s  ->  ftp://user:password@ftp.example.com/%2Fpath/file.zip;type=a
+    #
+    #     uri2 = URI::FTP.build({:host => 'ftp.example.com', 
+    #       :path => 'ruby/src'})
+    #     puts uri2.to_s  ->  ftp://ftp.example.com/ruby/src
     #
     def self.build(args)
+
+      # Fix the incoming path to be generic URL syntax
+      # FTP path  ->  URL path
+      # foo/bar       /foo/bar
+      # /foo/bar      /%2Ffoo/bar
+      #
+      if args.kind_of?(Array)
+        args[3] = '/' + args[3].sub(/^\//, '%2F')
+      else
+        args[:path] = '/' + args[:path].sub(/^\//, '%2F')
+      end
+
       tmp = Util::make_components_hash(self, args)
 
       if tmp[:typecode]
@@ -72,16 +103,14 @@ module URI
     #
     # == Description
     #
-    # Create a new URI::FTP object from ``generic'' components with no
-    # check.
+    # Creates a new URI::FTP object from generic URL components with no
+    # syntax checking.
     #
-    # == Usage
+    # Unlike build(), this method does not escape the path component as
+    # required by RFC1738; instead it is treated as per RFC2396.
     #
-    #   require 'uri'
-    #   p ftp = URI.parse("ftp://ftp.ruby-lang.org/pub/ruby/;type=d") 
-    #   # => #<URI::FTP:0x201fad08 URL:ftp://ftp.ruby-lang.org/pub/ruby/;type=d>
-    #   p ftp.typecode
-    #   # => "d"
+    # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+, 
+    # +opaque+, +query+ and +fragment+, in that order.
     #
     def initialize(*arg)
       super(*arg)
@@ -130,6 +159,27 @@ module URI
       return tmp
     end
 
+    # Returns the path from an FTP URI.
+    #
+    # RFC 1738 specifically states that the path for an FTP URI does not
+    # include the / which separates the URI path from the URI host. Example:
+    #
+    #     ftp://ftp.example.com/pub/ruby 
+    #
+    # The above URI indicates that the client should connect to 
+    # ftp.example.com then cd pub/ruby from the initial login directory.
+    #
+    # If you want to cd to an absolute directory, you must include an
+    # escaped / (%2F) in the path. Example:
+    #
+    #     ftp://ftp.example.com/%2Fpub/ruby
+    #
+    # This method will then return "/pub/ruby"
+    #
+    def path
+      return @path.sub(/^\//,'').sub(/^%2F/,'/')
+    end
+
     def to_s
       save_path = nil
       if @typecode
diff --git a/lib/uri/generic.rb b/lib/uri/generic.rb
index 51c2bf17f6..d166757fef 100644
--- a/lib/uri/generic.rb
+++ b/lib/uri/generic.rb
@@ -12,6 +12,7 @@ module URI
   
   #
   # Base class for all URI classes.
+  # Implements generic URI syntax as per RFC 2396.
   #
   class Generic
     include URI
diff --git a/lib/uri/http.rb b/lib/uri/http.rb
index 1f8bf587aa..87eb8893f2 100644
--- a/lib/uri/http.rb
+++ b/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
diff --git a/lib/uri/https.rb b/lib/uri/https.rb
index 78e5b9af12..9761636304 100644
--- a/lib/uri/https.rb
+++ b/lib/uri/https.rb
@@ -9,6 +9,10 @@
 require 'uri/http'
 
 module URI
+
+  # The default port for HTTPS URIs is 443, and the scheme is 'https:' rather
+  # than 'http:'. Other than that, HTTPS URIs are identical to HTTP URIs;
+  # see URI::HTTP.
   class HTTPS < HTTP
     DEFAULT_PORT = 443
   end
diff --git a/lib/uri/mailto.rb b/lib/uri/mailto.rb
index 0c93ae1c0d..44f04f2dd5 100644
--- a/lib/uri/mailto.rb
+++ b/lib/uri/mailto.rb
@@ -61,11 +61,29 @@ module URI
     #
     # == Description
     #
-    # Creates a new URI::MailTo object from components of URI::MailTo
-    # with check.  It is to and headers. It provided by an Array of a
-    # Hash. You can provide headers as String like
-    # "subject=subscribe&cc=addr" or Array like [["subject",
-    # "subscribe"], ["cc", "addr"]]
+    # Creates a new URI::MailTo object from components, with syntax checking.
+    #
+    # Components can be provided as an Array or Hash. If an Array is used,
+    # the components must be supplied as [to, headers].
+    #
+    # If a Hash is used, the keys are the component names preceded by colons.
+    #
+    # The headers can be supplied as a pre-encoded string, such as 
+    # "subject=subscribe&cc=address", or as an Array of Arrays like
+    # [['subject', 'subscribe'], ['cc', 'address']]
+    #
+    # Examples:
+    # 
+    #    require 'uri'
+    #    
+    #    m1 = URI::MailTo.build(['joe@example.com', 'subject=Ruby'])
+    #    puts m1.to_s  ->  mailto:joe@example.com?subject=Ruby
+    #    
+    #    m2 = URI::MailTo.build(['john@example.com', [['Subject', 'Ruby'], ['Cc', 'jack@example.com']]])
+    #    puts m2.to_s  ->  mailto:john@example.com?Subject=Ruby&Cc=jack@example.com
+    #    
+    #    m3 = URI::MailTo.build({:to => 'listman@example.com', :headers => [['subject', 'subscribe']]})
+    #    puts m3.to_s  ->  mailto:listman@example.com?subject=subscribe
     #
     def self.build(args)
       tmp = Util::make_components_hash(self, args)
@@ -104,9 +122,11 @@ module URI
     #
     # == Description
     #
-    # Creates a new URI::MailTo object from ``generic'' components with
-    # no check. Because, this method is usually called from URI::parse
-    # and the method checks validity of each components.
+    # Creates a new URI::MailTo object from generic URL components with
+    # no syntax checking.
+    #
+    # This method is usually called from URI::parse, which checks
+    # the validity of each component.
     #
     def initialize(*arg)
       super(*arg)
@@ -128,7 +148,11 @@ module URI
           "unrecognised opaque part for mailtoURL: #{@opaque}"
       end
     end
+
+    # The primary e-mail address of the URL, as a String
     attr_reader :to
+
+    # E-mail headers set by the URL, as an Array of Arrays
     attr_reader :headers
 
     def check_to(v)
@@ -203,8 +227,11 @@ module URI
           ''
         end
     end
+    
+    # Returns the RFC822 e-mail text equivalent of the URL, as a String.
+    #
+    # Example:
     #
-    # == Usage
     #   require 'uri'
     #
     #   uri = URI.parse("mailto:ruby-list@ruby-lang.org?Subject=subscribe&cc=myaddr")