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, 18 insertions, 18 deletions

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