* re.c (Init_Regexp): Document option constants. Patch by Vincent

	  Batts.  [Ruby 1.9 - Bug #4677]
	* lib/uri/common.rb (module URI):  Documentation for URI.  Patch by
	  Vincent Batts.  [Ruby 1.9- Bug #4677]
	* lib/uri/ftp.rb (module URI):  ditto
	* lib/uri/generic.rb (module URI):  ditto
	* lib/uri/http.rb (module URI):  ditto
	* lib/uri/https.rb (module URI):  ditto
	* lib/uri/ldap.rb (module URI):  ditto
	* lib/uri/ldaps.rb (module URI):  ditto
	* lib/uri/mailto.rb (module URI):  ditto
	* process.c (Init_process):  Document Process constants.  Patch by
	  Vincent Batts.  [Ruby 1.9- Bug #4677]


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

1 files changed, 68 insertions, 0 deletions

diff --git a/lib/uri/ldap.rb b/lib/uri/ldap.rb
index 6739a018af..561082a58e 100644
--- a/lib/uri/ldap.rb
+++ b/lib/uri/ldap.rb
@@ -20,8 +20,10 @@ module URI
   #
   class LDAP < Generic
 
+    # A Default port of 389 for URI::LDAP
     DEFAULT_PORT = 389
 
+    # An Array of the available components for URI::LDAP
     COMPONENT = [
       :scheme,
       :host, :port,
@@ -32,12 +34,40 @@ module URI
       :extensions,
     ].freeze
 
+    # Scopes available for the starting point.
+    #
+    # * 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 
+    #
     SCOPE = [
       SCOPE_ONE = 'one',
       SCOPE_SUB = 'sub',
       SCOPE_BASE = 'base',
     ].freeze
 
+    #
+    # == Description
+    #
+    # Create a new URI::LDAP object from components, with syntax checking.
+    #
+    # The components accepted are host, port, dn, attributes,
+    # scope, filter, and extensions.
+    #
+    # 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].
+    #
+    # Example:
+    #
+    #     newuri = URI::LDAP.build({:host => 'ldap.example.com',
+    #       :dn> => '/dc=example'})
+    #
+    #     newuri = URI::LDAP.build(["ldap.example.com", nil,
+    #       "/dc=example;dc=com", "query", nil, nil, nil])
+    #
     def self.build(args)
       tmp = Util::make_components_hash(self, args)
 
@@ -56,6 +86,23 @@ module URI
       return super(tmp)
     end
 
+    #
+    # == Description
+    #
+    # Create 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.
+    #
+    # Example:
+    #
+    #     uri = URI::LDAP.new("ldap", nil, "ldap.example.com", nil,
+    #       "/dc=example;dc=com", "query", nil, nil, nil, nil)
+    #
+    #
+    # See also URI::Generic.new
+    #
     def initialize(*arg)
       super(*arg)
 
@@ -67,11 +114,14 @@ module URI
       parse_query
     end
 
+    # 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
     def parse_query
       @attributes = nil
       @scope      = nil
@@ -89,6 +139,7 @@ module URI
     end
     private :parse_query
 
+    # private method to assemble +query+ from +attributes+, +scope+, +filter+ and +extensions+.
     def build_path_query
       @path = '/' + @dn
 
@@ -101,10 +152,12 @@ module URI
     end
     private :build_path_query
 
+    # returns dn.
     def dn
       @dn
     end
 
+    # private setter for dn +val+
     def set_dn(val)
       @dn = val
       build_path_query
@@ -112,15 +165,18 @@ module URI
     end
     protected :set_dn
 
+    # setter for dn +val+
     def dn=(val)
       set_dn(val)
       val
     end
 
+    # returns attributes.
     def attributes
       @attributes
     end
 
+    # private setter for attributes +val+
     def set_attributes(val)
       @attributes = val
       build_path_query
@@ -128,15 +184,18 @@ module URI
     end
     protected :set_attributes
 
+    # setter for attributes +val+
     def attributes=(val)
       set_attributes(val)
       val
     end
 
+    # returns scope.
     def scope
       @scope
     end
 
+    # private setter for scope +val+
     def set_scope(val)
       @scope = val
       build_path_query
@@ -144,15 +203,18 @@ module URI
     end
     protected :set_scope
 
+    # setter for scope +val+
     def scope=(val)
       set_scope(val)
       val
     end
 
+    # returns filter.
     def filter
       @filter
     end
 
+    # private setter for filter +val+
     def set_filter(val)
       @filter = val
       build_path_query
@@ -160,15 +222,18 @@ module URI
     end
     protected :set_filter
 
+    # setter for filter +val+
     def filter=(val)
       set_filter(val)
       val
     end
 
+    # returns extensions.
     def extensions
       @extensions
     end
 
+    # private setter for extensions +val+
     def set_extensions(val)
       @extensions = val
       build_path_query
@@ -176,11 +241,14 @@ module URI
     end
     protected :set_extensions
 
+    # 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+
     def hierarchical?
       false
     end