Docs and tests on URI.hierarchical?, URI.absolute?

Improve code coverage and clarify meaning of hierarchical based on RFC
text.

[Fix GH-1846]

From: Xavier Riley <xavriley@hotmail.com>

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

lib/uri/generic.rb

@@ -946,7 +946,25 @@ def fragment=(v)
     end
 
     #
-    # Checks if URI has a path
+    # Returns true if URI is hierarchical
+    #
+    # == Description
+    #
+    # URI has components listed in order of decreashing signficance 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
+    #   uri = URI.parse("mailto:joe@example.com")
+    #   => #<URI::MailTo mailto:joe@example.com>
+    #   uri.hierarchical?
+    #   # => false
     #
     def hierarchical?
       if @path
@@ -957,7 +975,7 @@ def hierarchical?
     end
 
     #
-    # Checks if URI is an absolute one
+    # Returns true if URI has a scheme (e.g. http:// or https://) specified
     #
     def absolute?
       if @scheme
@@ -969,7 +987,7 @@ def absolute?
     alias absolute absolute?
 
     #
-    # Checks if URI is relative
+    # Returns true if URI does not have a scheme (e.g. http:// or https://) specified
     #
     def relative?
       !absolute?

test/uri/test_generic.rb

@@ -774,6 +774,24 @@ def test_set_scheme
     assert_equal 'http://example', uri.to_s
   end
 
+  def test_hierarchical
+    hierarchical = URI.parse('http://a.b.c/example')
+    opaque = URI.parse('mailto:mduerst@ifi.unizh.ch')
+
+    assert hierarchical.hierarchical?
+    refute opaque.hierarchical?
+  end
+
+  def test_absolute
+    abs_uri = URI.parse('http://a.b.c/')
+    not_abs = URI.parse('a.b.c')
+
+    refute not_abs.absolute?
+
+    assert abs_uri.absolute
+    assert abs_uri.absolute?
+  end
+
   def test_ipv6
     assert_equal("[::1]", URI("http://[::1]/bar/baz").host)
     assert_equal("::1", URI("http://[::1]/bar/baz").hostname)