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

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