Improve docs for URI library

* lib/uri/generic.rb: [DOC] fix invalid example code to make it
  syntax highlighted; drop unnecessary `puts', `p'; adapt to current
  inspect format without Object id; do not display unnecessary return
  values in examples; fix or prevent unintended description lists;
  fix broken RDoc; fix grammar and typos.

* lib/uri.rb: ditto.
* lib/uri/common.rb: ditto.
* lib/uri/file.rb: ditto.
* lib/uri/ftp.rb: ditto.
* lib/uri/http.rb: ditto.
* lib/uri/ldap.rb: ditto.
* lib/uri/mailto.rb: ditto.
* lib/uri/rfc2396_parser.rb: ditto.

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

lib/uri.rb

@@ -1,34 +1,28 @@
 # frozen_string_literal: false
 # URI is a module providing classes to handle Uniform Resource Identifiers
-# (RFC2396[http://tools.ietf.org/html/rfc2396])
+# (RFC2396[http://tools.ietf.org/html/rfc2396]).
 #
 # == Features
 #
-# * Uniform handling of handling URIs
-# * Flexibility to introduce custom URI schemes
+# * Uniform way of handling URIs.
+# * Flexibility to introduce custom URI schemes.
 # * Flexibility to have an alternate URI::Parser (or just different patterns
-#   and regexp's)
+#   and regexp's).
 #
 # == Basic example
 #
 #   require 'uri'
 #
 #   uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413")
-#   #=> #<URI::HTTP:0x00000000b14880
-#         URL:http://foo.com/posts?id=30&limit=5#time=1305298413>
-#   uri.scheme
-#   #=> "http"
-#   uri.host
-#   #=> "foo.com"
-#   uri.path
-#   #=> "/posts"
-#   uri.query
-#   #=> "id=30&limit=5"
-#   uri.fragment
-#   #=> "time=1305298413"
-#
-#   uri.to_s
-#   #=> "http://foo.com/posts?id=30&limit=5#time=1305298413"
+#   #=> #<URI::HTTP http://foo.com/posts?id=30&limit=5#time=1305298413>
+#
+#   uri.scheme    #=> "http"
+#   uri.host      #=> "foo.com"
+#   uri.path      #=> "/posts"
+#   uri.query     #=> "id=30&limit=5"
+#   uri.fragment  #=> "time=1305298413"
+#
+#   uri.to_s      #=> "http://foo.com/posts?id=30&limit=5#time=1305298413"
 #
 # == Adding custom URIs
 #
@@ -41,18 +35,18 @@
 #   #=> URI::RSYNC
 #
 #   URI.scheme_list
-#   #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP, "HTTPS"=>URI::HTTPS,
-#        "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, "MAILTO"=>URI::MailTo,
-#        "RSYNC"=>URI::RSYNC}
+#   #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP,
+#   #    "HTTPS"=>URI::HTTPS, "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS,
+#   #    "MAILTO"=>URI::MailTo, "RSYNC"=>URI::RSYNC}
 #
 #   uri = URI("rsync://rsync.foo.com")
-#   #=> #<URI::RSYNC:0x00000000f648c8 URL:rsync://rsync.foo.com>
+#   #=> #<URI::RSYNC rsync://rsync.foo.com>
 #
 # == RFC References
 #
-# A good place to view an RFC spec is http://www.ietf.org/rfc.html
+# A good place to view an RFC spec is http://www.ietf.org/rfc.html.
 #
-# Here is a list of all related RFC's.
+# Here is a list of all related RFC's:
 # - RFC822[http://tools.ietf.org/html/rfc822]
 # - RFC1738[http://tools.ietf.org/html/rfc1738]
 # - RFC2255[http://tools.ietf.org/html/rfc2255]

lib/uri/common.rb

@@ -61,7 +61,7 @@ def make_components_hash(klass, array_hash)
     module_function :make_components_hash
   end
 
-  # module for escaping unsafe characters with codes.
+  # Module for escaping unsafe characters with codes.
   module Escape
     #
     # == Synopsis
@@ -90,13 +90,12 @@ module Escape
     #   require 'uri'
     #
     #   enc_uri = URI.escape("http://example.com/?a=\11\15")
-    #   p enc_uri
     #   # => "http://example.com/?a=%09%0D"
     #
-    #   p URI.unescape(enc_uri)
+    #   URI.unescape(enc_uri)
     #   # => "http://example.com/?a=\t\r"
     #
-    #   p URI.escape("@?@!", "!?")
+    #   URI.escape("@?@!", "!?")
     #   # => "@%3F@%21"
     #
     def escape(*arg)
@@ -112,7 +111,7 @@ def escape(*arg)
     # == Args
     #
     # +str+::
-    #   Unescapes the string.
+    #   String to unescape.
     #
     # == Description
     #
@@ -125,10 +124,9 @@ def escape(*arg)
     #   require 'uri'
     #
     #   enc_uri = URI.escape("http://example.com/?a=\11\15")
-    #   p enc_uri
     #   # => "http://example.com/?a=%09%0D"
     #
-    #   p URI.unescape(enc_uri)
+    #   URI.unescape(enc_uri)
     #   # => "http://example.com/?a=\t\r"
     #
     def unescape(*arg)
@@ -142,7 +140,7 @@ def unescape(*arg)
   include REGEXP
 
   @@schemes = {}
-  # Returns a Hash of the defined schemes
+  # Returns a Hash of the defined schemes.
   def self.scheme_list
     @@schemes
   end
@@ -178,21 +176,21 @@ class BadURIError < Error; end
   #
   # Splits the string on following parts and returns array with result:
   #
-  #   * Scheme
-  #   * Userinfo
-  #   * Host
-  #   * Port
-  #   * Registry
-  #   * Path
-  #   * Opaque
-  #   * Query
-  #   * Fragment
+  # * Scheme
+  # * Userinfo
+  # * Host
+  # * Port
+  # * Registry
+  # * Path
+  # * Opaque
+  # * Query
+  # * Fragment
   #
   # == Usage
   #
   #   require 'uri'
   #
-  #   p URI.split("http://www.ruby-lang.org/")
+  #   URI.split("http://www.ruby-lang.org/")
   #   # => ["http", nil, "www.ruby-lang.org", nil, nil, "/", nil, nil, nil]
   #
   def self.split(uri)
@@ -215,19 +213,18 @@ def self.split(uri)
   #
   # == Raises
   #
-  # URI::InvalidURIError
+  # URI::InvalidURIError::
   #   Raised if URI given is not a correct one.
   #
   # == Usage
   #
   #   require 'uri'
   #
   #   uri = URI.parse("http://www.ruby-lang.org/")
-  #   p uri
-  #   # => #<URI::HTTP:0x202281be URL:http://www.ruby-lang.org/>
-  #   p uri.scheme
+  #   # => #<URI::HTTP http://www.ruby-lang.org/>
+  #   uri.scheme
   #   # => "http"
-  #   p uri.host
+  #   uri.host
   #   # => "www.ruby-lang.org"
   #
   # It's recommended to first ::escape the provided +uri_str+ if there are any
@@ -255,21 +252,20 @@ def self.parse(uri)
   #
   #   require 'uri'
   #
-  #   p URI.join("http://example.com/","main.rbx")
-  #   # => #<URI::HTTP:0x2022ac02 URL:http://example.com/main.rbx>
+  #   URI.join("http://example.com/","main.rbx")
+  #   # => #<URI::HTTP http://example.com/main.rbx>
   #
-  #   p URI.join('http://example.com', 'foo')
-  #   # => #<URI::HTTP:0x01ab80a0 URL:http://example.com/foo>
+  #   URI.join('http://example.com', 'foo')
+  #   # => #<URI::HTTP http://example.com/foo>
   #
-  #   p URI.join('http://example.com', '/foo', '/bar')
-  #   # => #<URI::HTTP:0x01aaf0b0 URL:http://example.com/bar>
+  #   URI.join('http://example.com', '/foo', '/bar')
+  #   # => #<URI::HTTP http://example.com/bar>
   #
-  #   p URI.join('http://example.com', '/foo', 'bar')
-  #   # => #<URI::HTTP:0x801a92af0 URL:http://example.com/bar>
-  #
-  #   p URI.join('http://example.com', '/foo/', 'bar')
-  #   # => #<URI::HTTP:0x80135a3a0 URL:http://example.com/foo/bar>
+  #   URI.join('http://example.com', '/foo', 'bar')
+  #   # => #<URI::HTTP http://example.com/bar>
   #
+  #   URI.join('http://example.com', '/foo/', 'bar')
+  #   # => #<URI::HTTP http://example.com/foo/bar>
   #
   def self.join(*str)
     RFC3986_PARSER.join(*str)
@@ -285,7 +281,7 @@ def self.join(*str)
   # +str+::
   #   String to extract URIs from.
   # +schemes+::
-  #   Limit URI matching to a specific schemes.
+  #   Limit URI matching to specific schemes.
   #
   # == Description
   #
@@ -316,6 +312,7 @@ def self.extract(str, schemes = nil, &block)
   #   whose scheme is one of the match_schemes.
   #
   # == Description
+  #
   # Returns a Regexp object which matches to URI-like strings.
   # The Regexp object returned by this method includes arbitrary
   # number of capture group (parentheses).  Never rely on it's number.
@@ -328,7 +325,7 @@ def self.extract(str, schemes = nil, &block)
   #   html_string.slice(URI.regexp)
   #
   #   # remove ftp URIs
-  #   html_string.sub(URI.regexp(['ftp'])
+  #   html_string.sub(URI.regexp(['ftp']), '')
   #
   #   # You should not rely on the number of parentheses
   #   html_string.scan(URI.regexp) do |*matches|
@@ -360,17 +357,17 @@ def self.regexp(schemes = nil)
   HTML5ASCIIINCOMPAT = defined? Encoding::UTF_7 ? [Encoding::UTF_7, Encoding::UTF_16BE, Encoding::UTF_16LE,
     Encoding::UTF_32BE, Encoding::UTF_32LE] : [] # :nodoc:
 
-  # Encode given +str+ to URL-encoded form data.
+  # Encodes given +str+ to URL-encoded form data.
   #
   # This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP
   # (ASCII space) to + and converts others to %XX.
   #
   # If +enc+ is given, convert +str+ to the encoding before percent encoding.
   #
   # This is an implementation of
-  # http://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data
+  # http://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data.
   #
-  # See URI.decode_www_form_component, URI.encode_www_form
+  # See URI.decode_www_form_component, URI.encode_www_form.
   def self.encode_www_form_component(str, enc=nil)
     str = str.to_s.dup
     if str.encoding != Encoding::ASCII_8BIT
@@ -384,25 +381,25 @@ def self.encode_www_form_component(str, enc=nil)
     str.force_encoding(Encoding::US_ASCII)
   end
 
-  # Decode given +str+ of URL-encoded form data.
+  # Decodes given +str+ of URL-encoded form data.
   #
   # This decodes + to SP.
   #
-  # See URI.encode_www_form_component, URI.decode_www_form
+  # See URI.encode_www_form_component, URI.decode_www_form.
   def self.decode_www_form_component(str, enc=Encoding::UTF_8)
     raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/ =~ str
     str.b.gsub(/\+|%\h\h/, TBLDECWWWCOMP_).force_encoding(enc)
   end
 
-  # Generate URL-encoded form data from given +enum+.
+  # Generates URL-encoded form data from given +enum+.
   #
   # This generates application/x-www-form-urlencoded data defined in HTML5
   # from given an Enumerable object.
   #
   # This internally uses URI.encode_www_form_component(str).
   #
   # This method doesn't convert the encoding of given items, so convert them
-  # before call this method if you want to send data as other than original
+  # before calling this method if you want to send data as other than original
   # encoding or mixed encoding data. (Strings which are encoded in an HTML5
   # ASCII incompatible encoding are converted to UTF-8.)
   #
@@ -420,7 +417,7 @@ def self.decode_www_form_component(str, enc=Encoding::UTF_8)
   #    URI.encode_www_form([["q", "ruby"], ["q", "perl"], ["lang", "en"]])
   #    #=> "q=ruby&q=perl&lang=en"
   #
-  # See URI.encode_www_form_component, URI.decode_www_form
+  # See URI.encode_www_form_component, URI.decode_www_form.
   def self.encode_www_form(enum, enc=nil)
     enum.map do |k,v|
       if v.nil?
@@ -441,22 +438,22 @@ def self.encode_www_form(enum, enc=nil)
     end.join('&')
   end
 
-  # Decode URL-encoded form data from given +str+.
+  # Decodes URL-encoded form data from given +str+.
   #
   # This decodes application/x-www-form-urlencoded data
-  # and returns array of key-value array.
+  # and returns an array of key-value arrays.
   #
-  # This refers http://url.spec.whatwg.org/#concept-urlencoded-parser ,
-  # so this supports only &-separator, don't support ;-separator.
+  # This refers http://url.spec.whatwg.org/#concept-urlencoded-parser,
+  # so this supports only &-separator, and doesn't support ;-separator.
   #
   #    ary = URI.decode_www_form("a=1&a=2&b=3")
-  #    p ary                  #=> [['a', '1'], ['a', '2'], ['b', '3']]
-  #    p ary.assoc('a').last  #=> '1'
-  #    p ary.assoc('b').last  #=> '3'
-  #    p ary.rassoc('a').last #=> '2'
-  #    p Hash[ary]            # => {"a"=>"2", "b"=>"3"}
+  #    ary                   #=> [['a', '1'], ['a', '2'], ['b', '3']]
+  #    ary.assoc('a').last   #=> '1'
+  #    ary.assoc('b').last   #=> '3'
+  #    ary.rassoc('a').last  #=> '2'
+  #    Hash[ary]             #=> {"a"=>"2", "b"=>"3"}
   #
-  # See URI.decode_www_form_component, URI.encode_www_form
+  # See URI.decode_www_form_component, URI.encode_www_form.
   def self.decode_www_form(str, enc=Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false)
     raise ArgumentError, "the input of #{self.name}.#{__method__} must be ASCII only string" unless str.ascii_only?
     ary = []
@@ -734,7 +731,7 @@ def self.get_encoding(label)
 module Kernel
 
   #
-  # Returns +uri+ converted to a URI object.
+  # Returns +uri+ converted to an URI object.
   #
   def URI(uri)
     if uri.is_a?(URI::Generic)

lib/uri/file.rb

@@ -49,9 +49,9 @@ def self.build(args)
       super(tmp)
     end
 
-    # protected setter for the host component +v+
+    # Protected setter for the host component +v+.
     #
-    # see also URI::Generic.host=
+    # See also URI::Generic.host=.
     #
     def set_host(v)
       v = "" if v.nil? || v == "localhost"