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

1 files changed, 155 insertions, 175 deletions

diff --git a/lib/uri/generic.rb b/lib/uri/generic.rb
index 7a05438f88..4791151965 100644
--- a/lib/uri/generic.rb
+++ b/lib/uri/generic.rb
@@ -23,26 +23,26 @@ module URI
     include URI
 
     #
-    # A Default port of nil for URI::Generic
+    # A Default port of nil for URI::Generic.
     #
     DEFAULT_PORT = nil
 
     #
-    # Returns default port
+    # Returns default port.
     #
     def self.default_port
       self::DEFAULT_PORT
     end
 
     #
-    # Returns default port
+    # Returns default port.
     #
     def default_port
       self.class.default_port
     end
 
     #
-    # An Array of the available components for URI::Generic
+    # An Array of the available components for URI::Generic.
     #
     COMPONENT = [
       :scheme,
@@ -68,14 +68,13 @@ module URI
     #
     # == Synopsis
     #
-    # See #new
+    # See ::new.
     #
     # == Description
     #
     # At first, tries to create a new URI::Generic instance using
     # URI::Generic::build. But, if exception URI::InvalidComponentError is raised,
-    # then it URI::Escape.escape all URI components and tries again.
-    #
+    # then it does URI::Escape.escape all URI components and tries again.
     #
     def self.build2(args)
       begin
@@ -106,14 +105,14 @@ module URI
     #
     # == Synopsis
     #
-    # See #new
+    # See ::new.
     #
     # == Description
     #
     # Creates a new URI::Generic instance from components of URI::Generic
     # with check.  Components are: scheme, userinfo, host, port, registry, path,
-    # opaque, query and fragment. You can provide arguments either by an Array or a Hash.
-    # See #new for hash keys to use or for order of array items.
+    # opaque, query, and fragment. You can provide arguments either by an Array or a Hash.
+    # See ::new for hash keys to use or for order of array items.
     #
     def self.build(args)
       if args.kind_of?(Array) &&
@@ -137,31 +136,32 @@ module URI
       tmp << true
       return self.new(*tmp)
     end
+
     #
     # == Args
     #
     # +scheme+::
     #   Protocol scheme, i.e. 'http','ftp','mailto' and so on.
     # +userinfo+::
-    #   User name and password, i.e. 'sdmitry:bla'
+    #   User name and password, i.e. 'sdmitry:bla'.
     # +host+::
-    #   Server host name
+    #   Server host name.
     # +port+::
-    #   Server port
+    #   Server port.
     # +registry+::
     #   Registry of naming authorities.
     # +path+::
-    #   Path on server
+    #   Path on server.
     # +opaque+::
-    #   Opaque part
+    #   Opaque part.
     # +query+::
-    #   Query data
+    #   Query data.
     # +fragment+::
-    #   A part of URI after '#' sign
+    #   Part of the URI after '#' character.
     # +parser+::
-    #   Parser for internal use [URI::DEFAULT_PARSER by default]
+    #   Parser for internal use [URI::DEFAULT_PARSER by default].
     # +arg_check+::
-    #   Check arguments [false by default]
+    #   Check arguments [false by default].
     #
     # == Description
     #
@@ -215,38 +215,37 @@ module URI
     end
 
     #
-    # returns the scheme component of the URI.
+    # Returns the scheme component of the URI.
     #
     #   URI("http://foo/bar/baz").scheme #=> "http"
     #
     attr_reader :scheme
 
-    # returns the host component of the URI.
+    # Returns the host component of the URI.
     #
     #   URI("http://foo/bar/baz").host #=> "foo"
     #
-    # It returns nil if no host component.
+    # It returns nil if no host component exists.
     #
     #   URI("mailto:foo@example.org").host #=> nil
     #
-    # The component doesn't contains the port number.
+    # The component does not contain the port number.
     #
     #   URI("http://foo:8080/bar/baz").host #=> "foo"
     #
-    # Since IPv6 addresses are wrapped by brackets in URIs,
-    # this method returns IPv6 addresses wrapped by brackets.
-    # This form is not appropriate to pass socket methods such as TCPSocket.open.
-    # If unwrapped host names are required, use "hostname" method.
+    # Since IPv6 addresses are wrapped with brackets in URIs,
+    # this method returns IPv6 addresses wrapped with brackets.
+    # This form is not appropriate to pass to socket methods such as TCPSocket.open.
+    # If unwrapped host names are required, use the #hostname method.
     #
-    #   URI("http://[::1]/bar/baz").host #=> "[::1]"
+    #   URI("http://[::1]/bar/baz").host     #=> "[::1]"
     #   URI("http://[::1]/bar/baz").hostname #=> "::1"
     #
     attr_reader :host
 
-    # returns the port component of the URI.
-    #
-    #   URI("http://foo/bar/baz").port #=> "80"
+    # Returns the port component of the URI.
     #
+    #   URI("http://foo/bar/baz").port      #=> "80"
     #   URI("http://foo:8080/bar/baz").port #=> "8080"
     #
     attr_reader :port
@@ -255,13 +254,13 @@ module URI
       nil
     end
 
-    # returns the path component of the URI.
+    # Returns the path component of the URI.
     #
     #   URI("http://foo/bar/baz").path #=> "/bar/baz"
     #
     attr_reader :path
 
-    # returns the query component of the URI.
+    # Returns the query component of the URI.
     #
     #   URI("http://foo/bar/baz?search=FooBar").query #=> "search=FooBar"
     #
@@ -278,15 +277,15 @@ module URI
     #
     attr_reader :opaque
 
-    # returns the fragment component of the URI.
+    # Returns the fragment component of the URI.
     #
     #   URI("http://foo/bar/baz?search=FooBar#ponies").fragment #=> "ponies"
     #
     attr_reader :fragment
 
-    # returns the parser to be used.
+    # Returns the parser to be used.
     #
-    # Unless a URI::Parser is defined, then DEFAULT_PARSER is used.
+    # Unless a URI::Parser is defined, DEFAULT_PARSER is used.
     #
     def parser
       if !defined?(@parser) || !@parser
@@ -296,7 +295,8 @@ module URI
       end
     end
 
-    # replace self by other URI object
+    # Replaces self by other URI object.
+    #
     def replace!(oth)
       if self.class != oth.class
         raise ArgumentError, "expected #{self.class} object"
@@ -316,7 +316,7 @@ module URI
     end
 
     #
-    # check the scheme +v+ component against the URI::Parser Regexp for :SCHEME
+    # Checks the scheme +v+ component against the URI::Parser Regexp for :SCHEME.
     #
     def check_scheme(v)
       if v && parser.regexp[:SCHEME] !~ v
@@ -328,9 +328,9 @@ module URI
     end
     private :check_scheme
 
-    # protected setter for the scheme component +v+
+    # Protected setter for the scheme component +v+.
     #
-    # see also URI::Generic.scheme=
+    # See also URI::Generic.scheme=.
     #
     def set_scheme(v)
       @scheme = v&.downcase
@@ -345,10 +345,10 @@ module URI
     #
     # == Description
     #
-    # public setter for the scheme component +v+.
-    # (with validation)
+    # Public setter for the scheme component +v+
+    # (with validation).
     #
-    # see also URI::Generic.check_scheme
+    # See also URI::Generic.check_scheme.
     #
     # == Usage
     #
@@ -356,9 +356,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com")
     #   uri.scheme = "https"
-    #   # =>  "https"
-    #   uri
-    #   #=> #<URI::HTTP:0x000000008e89e8 URL:https://my.example.com>
+    #   uri.to_s  #=> "https://my.example.com"
     #
     def scheme=(v)
       check_scheme(v)
@@ -367,13 +365,13 @@ module URI
     end
 
     #
-    # check the +user+ and +password+.
+    # Checks the +user+ and +password+.
     #
     # If +password+ is not provided, then +user+ is
     # split, using URI::Generic.split_userinfo, to
     # pull +user+ and +password.
     #
-    # see also URI::Generic.check_user, URI::Generic.check_password
+    # See also URI::Generic.check_user, URI::Generic.check_password.
     #
     def check_userinfo(user, password = nil)
       if !password
@@ -387,8 +385,8 @@ module URI
     private :check_userinfo
 
     #
-    # check the user +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :USERINFO
+    # Checks the user +v+ component for RFC2396 compliance
+    # and against the URI::Parser Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined,
     # with a user component defined.
@@ -411,8 +409,8 @@ module URI
     private :check_user
 
     #
-    # check the password +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :USERINFO
+    # Checks the password +v+ component for RFC2396 compliance
+    # and against the URI::Parser Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined,
     # with a user component defined.
@@ -439,7 +437,7 @@ module URI
     private :check_password
 
     #
-    # Sets userinfo, argument is string like 'name:pass'
+    # Sets userinfo, argument is string like 'name:pass'.
     #
     def userinfo=(userinfo)
       if userinfo.nil?
@@ -458,10 +456,10 @@ module URI
     #
     # == Description
     #
-    # public setter for the +user+ component.
-    # (with validation)
+    # Public setter for the +user+ component
+    # (with validation).
     #
-    # see also URI::Generic.check_user
+    # See also URI::Generic.check_user.
     #
     # == Usage
     #
@@ -469,9 +467,7 @@ module URI
     #
     #   uri = URI.parse("http://john:S3nsit1ve@my.example.com")
     #   uri.user = "sam"
-    #   # =>  "sam"
-    #   uri
-    #   #=> #<URI::HTTP:0x00000000881d90 URL:http://sam:V3ry_S3nsit1ve@my.example.com>
+    #   uri.to_s  #=> "http://sam:V3ry_S3nsit1ve@my.example.com"
     #
     def user=(user)
       check_user(user)
@@ -487,10 +483,10 @@ module URI
     #
     # == Description
     #
-    # public setter for the +password+ component.
-    # (with validation)
+    # Public setter for the +password+ component
+    # (with validation).
     #
-    # see also URI::Generic.check_password
+    # See also URI::Generic.check_password.
     #
     # == Usage
     #
@@ -498,9 +494,7 @@ module URI
     #
     #   uri = URI.parse("http://john:S3nsit1ve@my.example.com")
     #   uri.password = "V3ry_S3nsit1ve"
-    #   # =>  "V3ry_S3nsit1ve"
-    #   uri
-    #   #=> #<URI::HTTP:0x00000000881d90 URL:http://john:V3ry_S3nsit1ve@my.example.com>
+    #   uri.to_s  #=> "http://john:V3ry_S3nsit1ve@my.example.com"
     #
     def password=(password)
       check_password(password)
@@ -508,10 +502,10 @@ module URI
       # returns password
     end
 
-    # protect setter for the +user+ component, and +password+ if available.
-    # (with validation)
+    # Protected setter for the +user+ component, and +password+ if available
+    # (with validation).
     #
-    # see also URI::Generic.userinfo=
+    # See also URI::Generic.userinfo=.
     #
     def set_userinfo(user, password = nil)
       unless password
@@ -524,9 +518,9 @@ module URI
     end
     protected :set_userinfo
 
-    # protected setter for the user component +v+
+    # Protected setter for the user component +v+.
     #
-    # see also URI::Generic.user=
+    # See also URI::Generic.user=.
     #
     def set_user(v)
       set_userinfo(v, @password)
@@ -534,9 +528,9 @@ module URI
     end
     protected :set_user
 
-    # protected setter for the password component +v+
+    # Protected setter for the password component +v+.
     #
-    # see also URI::Generic.password=
+    # See also URI::Generic.password=.
     #
     def set_password(v)
       @password = v
@@ -544,8 +538,8 @@ module URI
     end
     protected :set_password
 
-    # returns the userinfo +ui+ as user, password
-    # if properly formatted as 'user:password'
+    # Returns the userinfo +ui+ as <code>[user, password]</code>
+    # if properly formatted as 'user:password'.
     def split_userinfo(ui)
       return nil, nil unless ui
       user, password = ui.split(':', 2)
@@ -554,13 +548,13 @@ module URI
     end
     private :split_userinfo
 
-    # escapes 'user:password' +v+ based on RFC 1738 section 3.1
+    # Escapes 'user:password' +v+ based on RFC 1738 section 3.1.
     def escape_userpass(v)
       parser.escape(v, /[@:\/]/o) # RFC 1738 section 3.1 #/
     end
     private :escape_userpass
 
-    # returns the userinfo, either as 'user' or 'user:password'
+    # Returns the userinfo, either as 'user' or 'user:password'.
     def userinfo
       if @user.nil?
         nil
@@ -571,19 +565,19 @@ module URI
       end
     end
 
-    # returns the user component
+    # Returns the user component.
     def user
       @user
     end
 
-    # returns the password component
+    # Returns the password component.
     def password
       @password
     end
 
     #
-    # check the host +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :HOST
+    # Checks the host +v+ component for RFC2396 compliance
+    # and against the URI::Parser Regexp for :HOST.
     #
     # Can not have a registry or opaque component defined,
     # with a host component defined.
@@ -603,9 +597,9 @@ module URI
     end
     private :check_host
 
-    # 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)
       @host = v
@@ -620,10 +614,10 @@ module URI
     #
     # == Description
     #
-    # public setter for the host component +v+.
-    # (with validation)
+    # Public setter for the host component +v+
+    # (with validation).
     #
-    # see also URI::Generic.check_host
+    # See also URI::Generic.check_host.
     #
     # == Usage
     #
@@ -631,9 +625,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com")
     #   uri.host = "foo.com"
-    #   # =>  "foo.com"
-    #   uri
-    #   #=> #<URI::HTTP:0x000000008e89e8 URL:http://foo.com>
+    #   uri.to_s  #=> "http://foo.com"
     #
     def host=(v)
       check_host(v)
@@ -641,32 +633,31 @@ module URI
       v
     end
 
-    # extract the host part of the URI and unwrap brackets for IPv6 addresses.
+    # Extract the host part of the URI and unwrap brackets for IPv6 addresses.
     #
-    # This method is same as URI::Generic#host except
+    # This method is the same as URI::Generic#host except
     # brackets for IPv6 (and future IP) addresses are removed.
     #
-    #   u = URI("http://[::1]/bar")
-    #   p u.hostname      #=> "::1"
-    #   p u.host          #=> "[::1]"
+    #   uri = URI("http://[::1]/bar")
+    #   uri.hostname      #=> "::1"
+    #   uri.host          #=> "[::1]"
     #
     def hostname
       v = self.host
       /\A\[(.*)\]\z/ =~ v ? $1 : v
     end
 
-    # set the host part of the URI as the argument with brackets for IPv6 addresses.
+    # Sets the host part of the URI as the argument with brackets for IPv6 addresses.
     #
-    # This method is same as URI::Generic#host= except
-    # the argument can be bare IPv6 address.
+    # This method is the same as URI::Generic#host= except
+    # the argument can be a bare IPv6 address.
     #
-    #   u = URI("http://foo/bar")
-    #   p u.to_s                  #=> "http://foo/bar"
-    #   u.hostname = "::1"
-    #   p u.to_s                  #=> "http://[::1]/bar"
+    #   uri = URI("http://foo/bar")
+    #   uri.hostname = "::1"
+    #   uri.to_s  #=> "http://[::1]/bar"
     #
-    # If the argument seems IPv6 address,
-    # it is wrapped by brackets.
+    # If the argument seems to be an IPv6 address,
+    # it is wrapped with brackets.
     #
     def hostname=(v)
       v = "[#{v}]" if /\A\[.*\]\z/ !~ v && /:/ =~ v
@@ -674,8 +665,8 @@ module URI
     end
 
     #
-    # check the port +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :PORT
+    # Checks the port +v+ component for RFC2396 compliance
+    # and against the URI::Parser Regexp for :PORT.
     #
     # Can not have a registry or opaque component defined,
     # with a port component defined.
@@ -695,9 +686,9 @@ module URI
     end
     private :check_port
 
-    # protected setter for the port component +v+
+    # Protected setter for the port component +v+.
     #
-    # see also URI::Generic.port=
+    # See also URI::Generic.port=.
     #
     def set_port(v)
       v = v.empty? ? nil : v.to_i unless !v || v.kind_of?(Integer)
@@ -713,10 +704,10 @@ module URI
     #
     # == Description
     #
-    # public setter for the port component +v+.
-    # (with validation)
+    # Public setter for the port component +v+
+    # (with validation).
     #
-    # see also URI::Generic.check_port
+    # See also URI::Generic.check_port.
     #
     # == Usage
     #
@@ -724,9 +715,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com")
     #   uri.port = 8080
-    #   # =>  8080
-    #   uri
-    #   #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com:8080>
+    #   uri.to_s  #=> "http://my.example.com:8080"
     #
     def port=(v)
       check_port(v)
@@ -749,9 +738,9 @@ module URI
     end
 
     #
-    # check the path +v+ component for RFC2396 compliance
+    # Checks the path +v+ component for RFC2396 compliance
     # and against the URI::Parser Regexp
-    # for :ABS_PATH and :REL_PATH
+    # for :ABS_PATH and :REL_PATH.
     #
     # Can not have a opaque component defined,
     # with a path component defined.
@@ -784,9 +773,9 @@ module URI
     end
     private :check_path
 
-    # protected setter for the path component +v+
+    # Protected setter for the path component +v+.
     #
-    # see also URI::Generic.path=
+    # See also URI::Generic.path=.
     #
     def set_path(v)
       @path = v
@@ -801,10 +790,10 @@ module URI
     #
     # == Description
     #
-    # public setter for the path component +v+.
-    # (with validation)
+    # Public setter for the path component +v+
+    # (with validation).
     #
-    # see also URI::Generic.check_path
+    # See also URI::Generic.check_path.
     #
     # == Usage
     #
@@ -812,9 +801,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com/pub/files")
     #   uri.path = "/faq/"
-    #   # =>  "/faq/"
-    #   uri
-    #   #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com/faq/>
+    #   uri.to_s  #=> "http://my.example.com/faq/"
     #
     def path=(v)
       check_path(v)
@@ -830,7 +817,7 @@ module URI
     #
     # == Description
     #
-    # public setter for the query component +v+.
+    # Public setter for the query component +v+.
     #
     # == Usage
     #
@@ -838,9 +825,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com/?id=25")
     #   uri.query = "id=1"
-    #   # =>  "id=1"
-    #   uri
-    #   #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com/?id=1>
+    #   uri.to_s  #=> "http://my.example.com/?id=1"
     #
     def query=(v)
       return @query = nil unless v
@@ -857,10 +842,10 @@ module URI
     end
 
     #
-    # check the opaque +v+ component for RFC2396 compliance and
-    # against the URI::Parser Regexp for :OPAQUE
+    # Checks the opaque +v+ component for RFC2396 compliance and
+    # against the URI::Parser Regexp for :OPAQUE.
     #
-    # Can not have a host, port, user or path component defined,
+    # Can not have a host, port, user, or path component defined,
     # with an opaque component defined.
     #
     def check_opaque(v)
@@ -881,9 +866,9 @@ module URI
     end
     private :check_opaque
 
-    # protected setter for the opaque component +v+
+    # Protected setter for the opaque component +v+.
     #
-    # see also URI::Generic.opaque=
+    # See also URI::Generic.opaque=.
     #
     def set_opaque(v)
       @opaque = v
@@ -898,10 +883,10 @@ module URI
     #
     # == Description
     #
-    # public setter for the opaque component +v+.
-    # (with validation)
+    # Public setter for the opaque component +v+
+    # (with validation).
     #
-    # see also URI::Generic.check_opaque
+    # See also URI::Generic.check_opaque.
     #
     def opaque=(v)
       check_opaque(v)
@@ -910,7 +895,7 @@ module URI
     end
 
     #
-    # check the fragment +v+ component against the URI::Parser Regexp for :FRAGMENT
+    # Checks the fragment +v+ component against the URI::Parser Regexp for :FRAGMENT.
     #
     #
     # == Args
@@ -920,8 +905,8 @@ module URI
     #
     # == Description
     #
-    # public setter for the fragment component +v+.
-    # (with validation)
+    # Public setter for the fragment component +v+
+    # (with validation).
     #
     # == Usage
     #
@@ -929,9 +914,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com/?id=25#time=1305212049")
     #   uri.fragment = "time=1305212086"
-    #   # =>  "time=1305212086"
-    #   uri
-    #   #=> #<URI::HTTP:0x000000007a81f8 URL:http://my.example.com/?id=25#time=1305212086>
+    #   uri.to_s  #=> "http://my.example.com/?id=25#time=1305212086"
     #
     def fragment=(v)
       return @fragment = nil unless v
@@ -947,25 +930,23 @@ module URI
     end
 
     #
-    # Returns true if URI is hierarchical
+    # Returns true if URI is hierarchical.
     #
     # == Description
     #
-    # URI has components listed in order of decreasing signficance from left to right
-    # see RFC3986 https://tools.ietf.org/html/rfc3986 1.2.3
+    # URI has components listed in order of decreasing significance from left to right,
+    # see RFC3986 https://tools.ietf.org/html/rfc3986 1.2.3.
     #
     # == Usage
     #
     #   require 'uri'
     #
     #   uri = URI.parse("http://my.example.com/")
-    #   => #<URI::HTTP http://my.example.com/>
     #   uri.hierarchical?
-    #   # => true
+    #   #=> true
     #   uri = URI.parse("mailto:joe@example.com")
-    #   => #<URI::MailTo mailto:joe@example.com>
     #   uri.hierarchical?
-    #   # => false
+    #   #=> false
     #
     def hierarchical?
       if @path
@@ -976,7 +957,7 @@ module URI
     end
 
     #
-    # Returns true if URI has a scheme (e.g. http:// or https://) specified
+    # Returns true if URI has a scheme (e.g. http:// or https://) specified.
     #
     def absolute?
       if @scheme
@@ -988,14 +969,14 @@ module URI
     alias absolute absolute?
 
     #
-    # Returns true if URI does not have a scheme (e.g. http:// or https://) specified
+    # Returns true if URI does not have a scheme (e.g. http:// or https://) specified.
     #
     def relative?
       !absolute?
     end
 
     #
-    # returns an Array of the path split on '/'
+    # Returns an Array of the path split on '/'.
     #
     def split_path(path)
       path.split("/", -1)
@@ -1077,7 +1058,7 @@ module URI
     #
     # == Description
     #
-    # Destructive form of #merge
+    # Destructive form of #merge.
     #
     # == Usage
     #
@@ -1085,8 +1066,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com")
     #   uri.merge!("/main.rbx?page=1")
-    #   p uri
-    #   # =>  #<URI::HTTP:0x2021f3b0 URL:http://my.example.com/main.rbx?page=1>
+    #   uri.to_s  # => "http://my.example.com/main.rbx?page=1"
     #
     def merge!(oth)
       t = merge(oth)
@@ -1106,15 +1086,15 @@ module URI
     #
     # == Description
     #
-    # Merges two URI's.
+    # Merges two URIs.
     #
     # == Usage
     #
     #   require 'uri'
     #
     #   uri = URI.parse("http://my.example.com")
-    #   p uri.merge("/main.rbx?page=1")
-    #   # =>  #<URI::HTTP:0x2021f3b0 URL:http://my.example.com/main.rbx?page=1>
+    #   uri.merge("/main.rbx?page=1")
+    #   # => "http://my.example.com/main.rbx?page=1"
     #
     def merge(oth)
       rel = parser.send(:convert_to_uri, oth)
@@ -1259,15 +1239,15 @@ module URI
     #
     # == Description
     #
-    # Calculates relative path from oth to self
+    # Calculates relative path from oth to self.
     #
     # == Usage
     #
     #   require 'uri'
     #
     #   uri = URI.parse('http://my.example.com/main.rbx?page=1')
-    #   p uri.route_from('http://my.example.com')
-    #   #=> #<URI::Generic:0x20218858 URL:/main.rbx?page=1>
+    #   uri.route_from('http://my.example.com')
+    #   #=> #<URI::Generic /main.rbx?page=1>
     #
     def route_from(oth)
       # you can modify `rel', but can not `oth'.
@@ -1299,15 +1279,15 @@ module URI
     #
     # == Description
     #
-    # Calculates relative path to oth from self
+    # Calculates relative path to oth from self.
     #
     # == Usage
     #
     #   require 'uri'
     #
     #   uri = URI.parse('http://my.example.com')
-    #   p uri.route_to('http://my.example.com/main.rbx?page=1')
-    #   #=> #<URI::Generic:0x2020c2f6 URL:/main.rbx?page=1>
+    #   uri.route_to('http://my.example.com/main.rbx?page=1')
+    #   #=> #<URI::Generic /main.rbx?page=1>
     #
     def route_to(oth)
       parser.send(:convert_to_uri, oth).route_from(self)
@@ -1333,7 +1313,7 @@ module URI
     end
 
     #
-    # Destructive version of #normalize
+    # Destructive version of #normalize.
     #
     def normalize!
       if path&.empty?
@@ -1348,7 +1328,7 @@ module URI
     end
 
     #
-    # Constructs String from URI
+    # Constructs String from URI.
     #
     def to_s
       str = ''.dup
@@ -1388,7 +1368,7 @@ module URI
     end
 
     #
-    # Compares two URIs
+    # Compares two URIs.
     #
     def ==(oth)
       if self.class == oth.class
@@ -1421,7 +1401,7 @@ module URI
 =end
 
 
-    # returns an Array of the components defined from the COMPONENT Array
+    # Returns an Array of the components defined from the COMPONENT Array.
     def component_ary
       component.collect do |x|
         self.send(x)
@@ -1432,18 +1412,18 @@ module URI
     # == Args
     #
     # +components+::
-    #    Multiple Symbol arguments defined in URI::HTTP
+    #    Multiple Symbol arguments defined in URI::HTTP.
     #
     # == Description
     #
-    # Selects specified components from URI
+    # Selects specified components from URI.
     #
     # == Usage
     #
     #   require 'uri'
     #
     #   uri = URI.parse('http://myuser:mypass@my.example.com/test.rbx')
-    #   p uri.select(:userinfo, :host, :path)
+    #   uri.select(:userinfo, :host, :path)
     #   # => ["myuser:mypass", "my.example.com", "/test.rbx"]
     #
     def select(*components)
@@ -1469,8 +1449,8 @@ module URI
     #
     # == Description
     #
-    # attempts to parse other URI +oth+,
-    # returns [parsed_oth, self]
+    # Attempts to parse other URI +oth+,
+    # returns [parsed_oth, self].
     #
     # == Usage
     #
@@ -1478,7 +1458,7 @@ module URI
     #
     #   uri = URI.parse("http://my.example.com")
     #   uri.coerce("http://foo.com")
-    #   #=> [#<URI::HTTP:0x00000000bcb028 URL:http://foo.com/>, #<URI::HTTP:0x00000000d92178 URL:http://my.example.com>]
+    #   #=> [#<URI::HTTP http://foo.com>, #<URI::HTTP http://my.example.com>]
     #
     def coerce(oth)
       case oth
@@ -1491,15 +1471,15 @@ module URI
       return oth, self
     end
 
-    # returns a proxy URI.
+    # Returns a proxy URI.
     # The proxy URI is obtained from environment variables such as http_proxy,
     # ftp_proxy, no_proxy, etc.
     # If there is no proper proxy, nil is returned.
     #
-    # If the optional parameter, +env+, is specified, it is used instead of ENV.
+    # If the optional parameter +env+ is specified, it is used instead of ENV.
     #
     # Note that capitalized variables (HTTP_PROXY, FTP_PROXY, NO_PROXY, etc.)
-    # are examined too.
+    # are examined, too.
     #
     # But http_proxy and HTTP_PROXY is treated specially under CGI environment.
     # It's because HTTP_PROXY may be set by Proxy: header.