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, 19 insertions, 25 deletions

diff --git a/lib/uri.rb b/lib/uri.rb
index b123fa8801..9b6bde91c0 100644
--- a/lib/uri.rb
+++ b/lib/uri.rb
@@ -1,34 +1,28 @@
 # frozen_string_literal: false
 # URI is a module providing classes to handle Uniform Resource Identifiers
-# (RFC2396[http://tools.ietf.org/html/rfc2396])
+# (RFC2396[http://tools.ietf.org/html/rfc2396]).
 #
 # == Features
 #
-# * Uniform handling of handling URIs
-# * Flexibility to introduce custom URI schemes
+# * Uniform way of handling URIs.
+# * Flexibility to introduce custom URI schemes.
 # * Flexibility to have an alternate URI::Parser (or just different patterns
-#   and regexp's)
+#   and regexp's).
 #
 # == Basic example
 #
 #   require 'uri'
 #
 #   uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413")
-#   #=> #<URI::HTTP:0x00000000b14880
-#         URL:http://foo.com/posts?id=30&limit=5#time=1305298413>
-#   uri.scheme
-#   #=> "http"
-#   uri.host
-#   #=> "foo.com"
-#   uri.path
-#   #=> "/posts"
-#   uri.query
-#   #=> "id=30&limit=5"
-#   uri.fragment
-#   #=> "time=1305298413"
-#
-#   uri.to_s
-#   #=> "http://foo.com/posts?id=30&limit=5#time=1305298413"
+#   #=> #<URI::HTTP http://foo.com/posts?id=30&limit=5#time=1305298413>
+#
+#   uri.scheme    #=> "http"
+#   uri.host      #=> "foo.com"
+#   uri.path      #=> "/posts"
+#   uri.query     #=> "id=30&limit=5"
+#   uri.fragment  #=> "time=1305298413"
+#
+#   uri.to_s      #=> "http://foo.com/posts?id=30&limit=5#time=1305298413"
 #
 # == Adding custom URIs
 #
@@ -41,18 +35,18 @@
 #   #=> URI::RSYNC
 #
 #   URI.scheme_list
-#   #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP, "HTTPS"=>URI::HTTPS,
-#        "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, "MAILTO"=>URI::MailTo,
-#        "RSYNC"=>URI::RSYNC}
+#   #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP,
+#   #    "HTTPS"=>URI::HTTPS, "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS,
+#   #    "MAILTO"=>URI::MailTo, "RSYNC"=>URI::RSYNC}
 #
 #   uri = URI("rsync://rsync.foo.com")
-#   #=> #<URI::RSYNC:0x00000000f648c8 URL:rsync://rsync.foo.com>
+#   #=> #<URI::RSYNC rsync://rsync.foo.com>
 #
 # == RFC References
 #
-# A good place to view an RFC spec is http://www.ietf.org/rfc.html
+# A good place to view an RFC spec is http://www.ietf.org/rfc.html.
 #
-# Here is a list of all related RFC's.
+# Here is a list of all related RFC's:
 # - RFC822[http://tools.ietf.org/html/rfc822]
 # - RFC1738[http://tools.ietf.org/html/rfc1738]
 # - RFC2255[http://tools.ietf.org/html/rfc2255]