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

8 files changed, 325 insertions, 348 deletions

diff --git a/lib/uri/common.rb b/lib/uri/common.rb
index 292708c152..7200f8b1d7 100644
--- a/lib/uri/common.rb
+++ b/lib/uri/common.rb
@@ -61,7 +61,7 @@ module URI
     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 URI
     #   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 @@ module URI
     # == Args
     #
     # +str+::
-    #   Unescapes the string.
+    #   String to unescape.
     #
     # == Description
     #
@@ -125,10 +124,9 @@ module URI
     #   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 @@ module URI
   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 @@ module URI
   #
   # 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,7 +213,7 @@ module URI
   #
   # == Raises
   #
-  # URI::InvalidURIError
+  # URI::InvalidURIError::
   #   Raised if URI given is not a correct one.
   #
   # == Usage
@@ -223,11 +221,10 @@ module URI
   #   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 @@ module 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 @@ module URI
   # +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 @@ module URI
   #   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 @@ module URI
   #   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,7 +357,7 @@ module URI
   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.
@@ -368,9 +365,9 @@ module URI
   # 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,17 +381,17 @@ module URI
     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.
@@ -402,7 +399,7 @@ module URI
   # 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 @@ module URI
   #    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 @@ module URI
     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 @@ end # module URI
 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)
diff --git a/lib/uri/file.rb b/lib/uri/file.rb
index ffdd4aaa02..6c959be50d 100644
--- a/lib/uri/file.rb
+++ b/lib/uri/file.rb
@@ -49,9 +49,9 @@ module URI
       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"
diff --git a/lib/uri/ftp.rb b/lib/uri/ftp.rb
index 90c1403ce6..bc9c9c3c65 100644
--- a/lib/uri/ftp.rb
+++ b/lib/uri/ftp.rb
@@ -21,11 +21,11 @@ module URI
   # http://tools.ietf.org/html/draft-hoffman-ftp-uri-04
   #
   class FTP < Generic
-    # A Default port of 21 for URI::FTP
+    # A Default port of 21 for URI::FTP.
     DEFAULT_PORT = 21
 
     #
-    # An Array of the available components for URI::FTP
+    # An Array of the available components for URI::FTP.
     #
     COMPONENT = [
       :scheme,
@@ -34,7 +34,7 @@ module URI
     ].freeze
 
     #
-    # Typecode is "a", "i" or "d".
+    # Typecode is "a", "i", or "d".
     #
     # * "a" indicates a text file (the FTP command was ASCII)
     # * "i" indicates a binary file (FTP command IMAGE)
@@ -42,8 +42,7 @@ module URI
     #
     TYPECODE = ['a', 'i', 'd'].freeze
 
-    # Typecode prefix
-    #  ';type='
+    # Typecode prefix ";type=".
     TYPECODE_PREFIX = ';type='.freeze
 
     def self.new2(user, password, host, port, path,
@@ -71,27 +70,29 @@ module URI
     #
     # Creates a new URI::FTP object from components, with syntax checking.
     #
-    # The components accepted are +userinfo+, +host+, +port+, +path+ and
+    # 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 an Array is used, the components must be passed in the
+    # order <code>[userinfo, host, port, path, typecode]</code>.
     #
     # If the path supplied is absolute, it will be escaped in order to
-    # make it absolute in the URI. Examples:
+    # make it absolute in the URI.
+    #
+    # Examples:
     #
     #     require 'uri'
     #
-    #     uri = URI::FTP.build(['user:password', 'ftp.example.com', nil,
+    #     uri1 = 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=i
+    #     uri1.to_s  # => "ftp://user:password@ftp.example.com/%2Fpath/file.zip;type=i"
     #
     #     uri2 = URI::FTP.build({:host => 'ftp.example.com',
     #       :path => 'ruby/src'})
-    #     puts uri2.to_s  ->  ftp://ftp.example.com/ruby/src
+    #     uri2.to_s  # => "ftp://ftp.example.com/ruby/src"
     #
     def self.build(args)
 
@@ -128,7 +129,7 @@ module URI
     # required by RFC1738; instead it is treated as per RFC2396.
     #
     # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+,
-    # +opaque+, +query+ and +fragment+, in that order.
+    # +opaque+, +query+, and +fragment+, in that order.
     #
     def initialize(scheme,
                    userinfo, host, port, registry,
@@ -155,13 +156,13 @@ module URI
       end
     end
 
-    # typecode accessor
+    # typecode accessor.
     #
-    # see URI::FTP::COMPONENT
+    # See URI::FTP::COMPONENT.
     attr_reader :typecode
 
-    # validates typecode +v+,
-    # returns a +true+ or +false+ boolean
+    # Validates typecode +v+,
+    # returns +true+ or +false+.
     #
     def check_typecode(v)
       if TYPECODE.include?(v)
@@ -173,9 +174,9 @@ module URI
     end
     private :check_typecode
 
-    # Private setter for the typecode +v+
+    # Private setter for the typecode +v+.
     #
-    # see also URI::FTP.typecode=
+    # See also URI::FTP.typecode=.
     #
     def set_typecode(v)
       @typecode = v
@@ -190,21 +191,20 @@ module URI
     #
     # == Description
     #
-    # public setter for the typecode +v+.
-    # (with validation)
+    # Public setter for the typecode +v+
+    # (with validation).
     #
-    # see also URI::FTP.check_typecode
+    # See also URI::FTP.check_typecode.
     #
     # == Usage
     #
     #   require 'uri'
     #
     #   uri = URI.parse("ftp://john@ftp.example.com/my_file.img")
-    #   #=> #<URI::FTP:0x00000000923650 URL:ftp://john@ftp.example.com/my_file.img>
+    #   #=> #<URI::FTP ftp://john@ftp.example.com/my_file.img>
     #   uri.typecode = "i"
-    #   # =>  "i"
     #   uri
-    #   #=> #<URI::FTP:0x00000000923650 URL:ftp://john@ftp.example.com/my_file.img;type=i>
+    #   #=> #<URI::FTP ftp://john@ftp.example.com/my_file.img;type=i>
     #
     def typecode=(typecode)
       check_typecode(typecode)
@@ -226,29 +226,29 @@ module 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+
+    # <code>ftp://ftp.example.com/pub/ruby</code>
     #
     # The above URI indicates that the client should connect to
-    # ftp.example.com then cd pub/ruby from the initial login directory.
+    # ftp.example.com then cd to 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+
+    # <code>ftp://ftp.example.com/%2Fpub/ruby</code>
     #
-    # This method will then return "/pub/ruby"
+    # This method will then return "/pub/ruby".
     #
     def path
       return @path.sub(/^\//,'').sub(/^%2F/,'/')
     end
 
-    # Private setter for the path of the URI::FTP
+    # Private setter for the path of the URI::FTP.
     def set_path(v)
       super("/" + v.sub(/^\//, "%2F"))
     end
     protected :set_path
 
-    # Returns a String representation of the URI::FTP
+    # Returns a String representation of the URI::FTP.
     def to_s
       save_path = nil
       if @typecode
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.
diff --git a/lib/uri/http.rb b/lib/uri/http.rb
index 0af1858efe..7d499f08d8 100644
--- a/lib/uri/http.rb
+++ b/lib/uri/http.rb
@@ -21,10 +21,10 @@ module URI
   # update. See <URL:http://support.microsoft.com/kb/834489>.
   #
   class HTTP < Generic
-    # A Default port of 80 for URI::HTTP
+    # A Default port of 80 for URI::HTTP.
     DEFAULT_PORT = 80
 
-    # An Array of the available components for URI::HTTP
+    # An Array of the available components for URI::HTTP.
     COMPONENT = %i[
       scheme
       userinfo host port
@@ -36,22 +36,22 @@ module URI
     #
     # == Description
     #
-    # Create a new URI::HTTP object from components, with syntax checking.
+    # Creates a new URI::HTTP object from components, with syntax checking.
     #
-    # The components accepted are userinfo, host, port, path, query and
+    # 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].
+    # If an Array is used, the components must be passed in the
+    # order <code>[userinfo, host, port, path, query, fragment]</code>.
     #
     # Example:
     #
-    #     newuri = URI::HTTP.build(host: 'www.example.com', path: '/foo/bar')
+    #     uri = URI::HTTP.build(host: 'www.example.com', path: '/foo/bar')
     #
-    #     newuri = URI::HTTP.build([nil, "www.example.com", nil, "/path",
+    #     uri = URI::HTTP.build([nil, "www.example.com", nil, "/path",
     #       "query", 'fragment'])
     #
     # Currently, if passed userinfo components this method generates
@@ -72,8 +72,8 @@ module URI
     #
     # Example:
     #
-    #     newuri = URI::HTTP.build(path: '/foo/bar', query: 'test=true')
-    #     newuri.request_uri # => "/foo/bar?test=true"
+    #     uri = URI::HTTP.build(path: '/foo/bar', query: 'test=true')
+    #     uri.request_uri #  => "/foo/bar?test=true"
     #
     def request_uri
       return unless @path
diff --git a/lib/uri/ldap.rb b/lib/uri/ldap.rb
index f7468a143a..6863fcfbc1 100644
--- a/lib/uri/ldap.rb
+++ b/lib/uri/ldap.rb
@@ -17,15 +17,16 @@ require 'uri/generic'
 module URI
 
   #
-  # LDAP URI SCHEMA (described in RFC2255)
+  # LDAP URI SCHEMA (described in RFC2255).
+  #--
   # ldap://<host>/<dn>[?<attrs>[?<scope>[?<filter>[?<extensions>]]]]
-  #
+  #++
   class LDAP < Generic
 
-    # A Default port of 389 for URI::LDAP
+    # A Default port of 389 for URI::LDAP.
     DEFAULT_PORT = 389
 
-    # An Array of the available components for URI::LDAP
+    # An Array of the available components for URI::LDAP.
     COMPONENT = [
       :scheme,
       :host, :port,
@@ -40,8 +41,8 @@ module URI
     #
     # * SCOPE_BASE - the Base DN
     # * SCOPE_ONE  - one level under the Base DN, not including the base DN and
-    #                not including any entries under this.
-    # * SCOPE_SUB  - subtress, all entries at all levels
+    #   not including any entries under this
+    # * SCOPE_SUB  - subtrees, all entries at all levels
     #
     SCOPE = [
       SCOPE_ONE = 'one',
@@ -52,7 +53,7 @@ module URI
     #
     # == Description
     #
-    # Create a new URI::LDAP object from components, with syntax checking.
+    # Creates a new URI::LDAP object from components, with syntax checking.
     #
     # The components accepted are host, port, dn, attributes,
     # scope, filter, and extensions.
@@ -60,15 +61,15 @@ module URI
     # 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
-    # [host, port, dn, attributes, scope, filter, extensions].
+    # If an Array is used, the components must be passed in the
+    # order <code>[host, port, dn, attributes, scope, filter, extensions]</code>.
     #
     # Example:
     #
-    #     newuri = URI::LDAP.build({:host => 'ldap.example.com',
+    #     uri = URI::LDAP.build({:host => 'ldap.example.com',
     #       :dn => '/dc=example'})
     #
-    #     newuri = URI::LDAP.build(["ldap.example.com", nil,
+    #     uri = URI::LDAP.build(["ldap.example.com", nil,
     #       "/dc=example;dc=com", "query", nil, nil, nil])
     #
     def self.build(args)
@@ -92,19 +93,18 @@ module URI
     #
     # == Description
     #
-    # Create a new URI::LDAP object from generic URI components as per
+    # Creates a new URI::LDAP object from generic URI components as per
     # RFC 2396. No LDAP-specific syntax checking is performed.
     #
     # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+,
-    # +opaque+, +query+ and +fragment+, in that order.
+    # +opaque+, +query+, and +fragment+, in that order.
     #
     # Example:
     #
     #     uri = URI::LDAP.new("ldap", nil, "ldap.example.com", nil, nil,
     #       "/dc=example;dc=com", nil, "query", nil)
     #
-    #
-    # See also URI::Generic.new
+    # See also URI::Generic.new.
     #
     def initialize(*arg)
       super(*arg)
@@ -117,14 +117,14 @@ module URI
       parse_query
     end
 
-    # private method to cleanup +dn+ from using the +path+ component attribute
+    # Private method to cleanup +dn+ from using the +path+ component attribute.
     def parse_dn
       @dn = @path[1..-1]
     end
     private :parse_dn
 
-    # private method to cleanup +attributes+, +scope+, +filter+ and +extensions+,
-    # from using the +query+ component attribute
+    # Private method to cleanup +attributes+, +scope+, +filter+, and +extensions+
+    # from using the +query+ component attribute.
     def parse_query
       @attributes = nil
       @scope      = nil
@@ -142,7 +142,7 @@ module URI
     end
     private :parse_query
 
-    # private method to assemble +query+ from +attributes+, +scope+, +filter+ and +extensions+.
+    # Private method to assemble +query+ from +attributes+, +scope+, +filter+, and +extensions+.
     def build_path_query
       @path = '/' + @dn
 
@@ -155,12 +155,12 @@ module URI
     end
     private :build_path_query
 
-    # returns dn.
+    # Returns dn.
     def dn
       @dn
     end
 
-    # private setter for dn +val+
+    # Private setter for dn +val+.
     def set_dn(val)
       @dn = val
       build_path_query
@@ -168,18 +168,18 @@ module URI
     end
     protected :set_dn
 
-    # setter for dn +val+
+    # Setter for dn +val+.
     def dn=(val)
       set_dn(val)
       val
     end
 
-    # returns attributes.
+    # Returns attributes.
     def attributes
       @attributes
     end
 
-    # private setter for attributes +val+
+    # Private setter for attributes +val+.
     def set_attributes(val)
       @attributes = val
       build_path_query
@@ -187,18 +187,18 @@ module URI
     end
     protected :set_attributes
 
-    # setter for attributes +val+
+    # Setter for attributes +val+.
     def attributes=(val)
       set_attributes(val)
       val
     end
 
-    # returns scope.
+    # Returns scope.
     def scope
       @scope
     end
 
-    # private setter for scope +val+
+    # Private setter for scope +val+.
     def set_scope(val)
       @scope = val
       build_path_query
@@ -206,18 +206,18 @@ module URI
     end
     protected :set_scope
 
-    # setter for scope +val+
+    # Setter for scope +val+.
     def scope=(val)
       set_scope(val)
       val
     end
 
-    # returns filter.
+    # Returns filter.
     def filter
       @filter
     end
 
-    # private setter for filter +val+
+    # Private setter for filter +val+.
     def set_filter(val)
       @filter = val
       build_path_query
@@ -225,18 +225,18 @@ module URI
     end
     protected :set_filter
 
-    # setter for filter +val+
+    # Setter for filter +val+.
     def filter=(val)
       set_filter(val)
       val
     end
 
-    # returns extensions.
+    # Returns extensions.
     def extensions
       @extensions
     end
 
-    # private setter for extensions +val+
+    # Private setter for extensions +val+.
     def set_extensions(val)
       @extensions = val
       build_path_query
@@ -244,14 +244,14 @@ module URI
     end
     protected :set_extensions
 
-    # setter for extensions +val+
+    # Setter for extensions +val+.
     def extensions=(val)
       set_extensions(val)
       val
     end
 
-    # Checks if URI has a path
-    # For URI::LDAP this will return +false+
+    # Checks if URI has a path.
+    # For URI::LDAP this will return +false+.
     def hierarchical?
       false
     end
diff --git a/lib/uri/mailto.rb b/lib/uri/mailto.rb
index 1494c3952b..542bd4e089 100644
--- a/lib/uri/mailto.rb
+++ b/lib/uri/mailto.rb
@@ -13,15 +13,15 @@ require 'uri/generic'
 module URI
 
   #
-  # RFC6068, The mailto URL scheme
+  # RFC6068, the mailto URL scheme.
   #
   class MailTo < Generic
     include REGEXP
 
-    # A Default port of nil for URI::MailTo
+    # A Default port of nil for URI::MailTo.
     DEFAULT_PORT = nil
 
-    # An Array of the available components for URI::MailTo
+    # An Array of the available components for URI::MailTo.
     COMPONENT = [ :scheme, :to, :headers ].freeze
 
     # :stopdoc:
@@ -62,26 +62,26 @@ module URI
     # 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].
+    # the components must be supplied as <code>[to, headers]</code>.
     #
     # 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']]
+    # <code>"subject=subscribe&cc=address"</code>, or as an Array of Arrays
+    # like <code>[['subject', 'subscribe'], ['cc', 'address']]</code>.
     #
     # Examples:
     #
     #    require 'uri'
     #
     #    m1 = URI::MailTo.build(['joe@example.com', 'subject=Ruby'])
-    #    puts m1.to_s  ->  mailto:joe@example.com?subject=Ruby
+    #    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
+    #    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
+    #    m3.to_s  # => "mailto:listman@example.com?subject=subscribe"
     #
     def self.build(args)
       tmp = Util.make_components_hash(self, args)
@@ -160,13 +160,13 @@ module URI
       end
     end
 
-    # The primary e-mail address of the URL, as a String
+    # 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
+    # E-mail headers set by the URL, as an Array of Arrays.
     attr_reader :headers
 
-    # check the to +v+ component
+    # Checks the to +v+ component.
     def check_to(v)
       return true unless v
       return true if v.size == 0
@@ -191,20 +191,20 @@ module URI
     end
     private :check_to
 
-    # private setter for to +v+
+    # Private setter for to +v+.
     def set_to(v)
       @to = v
     end
     protected :set_to
 
-    # setter for to +v+
+    # Setter for to +v+.
     def to=(v)
       check_to(v)
       set_to(v)
       v
     end
 
-    # check the headers +v+ component against either
+    # Checks the headers +v+ component against either
     # * HEADER_REGEXP
     def check_headers(v)
       return true unless v
@@ -218,7 +218,7 @@ module URI
     end
     private :check_headers
 
-    # private setter for headers +v+
+    # Private setter for headers +v+.
     def set_headers(v)
       @headers = []
       if v
@@ -229,14 +229,14 @@ module URI
     end
     protected :set_headers
 
-    # setter for headers +v+
+    # Setter for headers +v+.
     def headers=(v)
       check_headers(v)
       set_headers(v)
       v
     end
 
-    # Constructs String from URI
+    # Constructs String from URI.
     def to_s
       @scheme + ':' +
         if @to
diff --git a/lib/uri/rfc2396_parser.rb b/lib/uri/rfc2396_parser.rb
index 6a2d819152..a143437d8a 100644
--- a/lib/uri/rfc2396_parser.rb
+++ b/lib/uri/rfc2396_parser.rb
@@ -58,7 +58,7 @@ module URI
     # :startdoc:
   end # REGEXP
 
-  # class that Parses String's into URI's
+  # Class that Parses String's into URI's.
   #
   # It contains a Hash set of patterns and Regexp's that match and validate.
   #
@@ -88,12 +88,12 @@ module URI
     # == Examples
     #
     #   p = URI::Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})")
-    #   u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP:0xb78cf4f8 URL:http://example.jp/%uABCD>
+    #   u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP http://example.jp/%uABCD>
     #   URI.parse(u.to_s) #=> raises URI::InvalidURIError
     #
     #   s = "http://example.com/ABCD"
-    #   u1 = p.parse(s) #=> #<URI::HTTP:0xb78c3220 URL:http://example.com/ABCD>
-    #   u2 = URI.parse(s) #=> #<URI::HTTP:0xb78b6d54 URL:http://example.com/ABCD>
+    #   u1 = p.parse(s) #=> #<URI::HTTP http://example.com/ABCD>
+    #   u2 = URI.parse(s) #=> #<URI::HTTP http://example.com/ABCD>
     #   u1 == u2 #=> true
     #   u1.eql?(u2) #=> false
     #
@@ -109,15 +109,15 @@ module URI
 
     # The Hash of patterns.
     #
-    # see also URI::Parser.initialize_pattern
+    # See also URI::Parser.initialize_pattern.
     attr_reader :pattern
 
-    # The Hash of Regexp
+    # The Hash of Regexp.
     #
-    # see also URI::Parser.initialize_regexp
+    # See also URI::Parser.initialize_regexp.
     attr_reader :regexp
 
-    # Returns a split URI against regexp[:ABS_URI]
+    # Returns a split URI against regexp[:ABS_URI].
     def split(uri)
       case uri
       when ''
@@ -198,14 +198,14 @@ module URI
     #
     # == Description
     #
-    # parses +uri+ and constructs either matching URI scheme object
-    # (FTP, HTTP, HTTPS, LDAP, LDAPS, or MailTo) or URI::Generic
+    # Parses +uri+ and constructs either matching URI scheme object
+    # (file, FTP, HTTP, HTTPS, LDAP, LDAPS, or MailTo) or URI::Generic.
     #
     # == Usage
     #
     #   p = URI::Parser.new
     #   p.parse("ldap://ldap.example.com/dc=example?user=john")
-    #   #=> #<URI::LDAP:0x00000000b9e7e8 URL:ldap://ldap.example.com/dc=example?user=john>
+    #   #=> #<URI::LDAP ldap://ldap.example.com/dc=example?user=john>
     #
     def parse(uri)
       scheme, userinfo, host, port,
@@ -231,7 +231,7 @@ module URI
     #
     # == Description
     #
-    # Attempts to parse and merge a set of URIs
+    # Attempts to parse and merge a set of URIs.
     #
     def join(*uris)
       uris[0] = convert_to_uri(uris[0])
@@ -253,11 +253,11 @@ module URI
     #
     # == Description
     #
-    # Attempts to parse and merge a set of URIs
-    # If no +block+ given , then returns the result,
+    # Attempts to parse and merge a set of URIs.
+    # If no +block+ given, then returns the result,
     # else it calls +block+ for each element in result.
     #
-    # see also URI::Parser.make_regexp
+    # See also URI::Parser.make_regexp.
     #
     def extract(str, schemes = nil)
       if block_given?
@@ -270,8 +270,8 @@ module URI
       end
     end
 
-    # returns Regexp that is default self.regexp[:ABS_URI_REF],
-    # unless +schemes+ is provided. Then it is a Regexp.union with self.pattern[:X_ABS_URI]
+    # Returns Regexp that is default self.regexp[:ABS_URI_REF],
+    # unless +schemes+ is provided. Then it is a Regexp.union with self.pattern[:X_ABS_URI].
     def make_regexp(schemes = nil)
       unless schemes
         @regexp[:ABS_URI_REF]
@@ -294,7 +294,7 @@ module URI
     #
     # == Description
     #
-    # constructs a safe String from +str+, removing unsafe characters,
+    # Constructs a safe String from +str+, removing unsafe characters,
     # replacing them with codes.
     #
     def escape(str, unsafe = @regexp[:UNSAFE])
@@ -326,7 +326,7 @@ module URI
     #
     # == Description
     #
-    # Removes escapes from +str+
+    # Removes escapes from +str+.
     #
     def unescape(str, escaped = @regexp[:ESCAPED])
       enc = str.encoding
@@ -341,7 +341,7 @@ module URI
 
     private
 
-    # Constructs the default Hash of patterns
+    # Constructs the default Hash of patterns.
     def initialize_pattern(opts = {})
       ret = {}
       ret[:ESCAPED] = escaped = (opts.delete(:ESCAPED) || PATTERN::ESCAPED)
@@ -499,7 +499,7 @@ module URI
       ret
     end
 
-    # Constructs the default Hash of Regexp's
+    # Constructs the default Hash of Regexp's.
     def initialize_regexp(pattern)
       ret = {}