improve docs for URI::Generic

* lib/uri/generic.rb: [DOC] expand docs for URI::Generic#normalize
  to clarify what normalization means here.
  Reported by Robert Gleeson.  [ruby-core:58430] [Bug #9127]

* lib/uri/generic.rb: [DOC] fix indent for correct code block detection.

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

1 files changed, 21 insertions, 11 deletions

diff --git a/lib/uri/generic.rb b/lib/uri/generic.rb
index 80d9616c1e..14e8be6ac0 100644
--- a/lib/uri/generic.rb
+++ b/lib/uri/generic.rb
@@ -271,7 +271,7 @@ module URI
     #
     # Portion of the path that does make use of the slash '/'.
     # The path typically refers to the absolute path and the opaque part.
-    #  (see RFC2396 Section 3 and 5.2)
+    # (See RFC2396 Section 3 and 5.2.)
     #
     attr_reader :opaque
 
@@ -643,9 +643,9 @@ module URI
     # This method is 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]"
+    #   u = URI("http://[::1]/bar")
+    #   p u.hostname      #=> "::1"
+    #   p u.host          #=> "[::1]"
     #
     def hostname
       v = self.host
@@ -657,10 +657,10 @@ module URI
     # This method is same as URI::Generic#host= except
     # the argument can be 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"
+    #   u = URI("http://foo/bar")
+    #   p u.to_s                  #=> "http://foo/bar"
+    #   u.hostname = "::1"
+    #   p u.to_s                  #=> "http://[::1]/bar"
     #
     # If the argument seems IPv6 address,
     # it is wrapped by brackets.
@@ -1293,7 +1293,17 @@ module URI
     end
 
     #
-    # Returns normalized URI
+    # Returns normalized URI.
+    #
+    #   require 'uri'
+    #
+    #   URI("HTTP://my.EXAMPLE.com").normalize
+    #   #=> #<URI::HTTP http://my.example.com/>
+    #
+    # Normalization here means:
+    #
+    # * scheme and host are converted to lowercase,
+    # * an empty path component is set to "/".
     #
     def normalize
       uri = dup
@@ -1438,8 +1448,8 @@ module URI
     #
     # == Description
     #
-    #  attempt to parse other URI +oth+
-    #  return [parsed_oth, self]
+    # attempts to parse other URI +oth+,
+    # returns [parsed_oth, self]
     #
     # == Usage
     #