From d85cc21fad673fa632fe946d46ad014ab4ce0b6f Mon Sep 17 00:00:00 2001
From: blackhedd <blackhedd@005445c4-6811-0410-8301-cae4f0071d1d>
Date: Tue, 2 May 2006 00:10:24 +0000
Subject: [PATCH] documented the Entry class

---
 lib/net/ldap.rb       |  4 ++--
 lib/net/ldap/entry.rb | 47 +++++++++++++++++++++++++++++++++++++++----
 2 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/lib/net/ldap.rb b/lib/net/ldap.rb
index 7a9af92..9e981fa 100644
--- a/lib/net/ldap.rb
+++ b/lib/net/ldap.rb
@@ -181,11 +181,11 @@ module Net
   # the attribute values stored in the directory for a particular entity.
   # #modify may add or delete attributes (which are lists of values) or it change attributes by
   # adding to or deleting from their values.
-  # There are three easier methods to modify an entry's attribute values:
+  # Net::LDAP provides three easier methods to modify an entry's attribute values:
   # #add_attribute, #replace_attribute, and #delete_attribute.
   #
   # ==== Delete
-  # #delete operation specifies an entity DN. If it succeeds, the entity and all its attributes
+  # #delete specifies an entity DN. If it succeeds, the entity and all its attributes
   # is removed from the directory.
   #
   # ==== Rename (or Modify RDN)
diff --git a/lib/net/ldap/entry.rb b/lib/net/ldap/entry.rb
index 3d89a56..598eb37 100644
--- a/lib/net/ldap/entry.rb
+++ b/lib/net/ldap/entry.rb
@@ -33,15 +33,43 @@ module Net
 class LDAP
 
 
+  # Objects of this class represent individual entries in an LDAP
+  # directory. User code generally does not instantiate this class.
+  # Net::LDAP#search provides objects of this class to user code,
+  # either as block parameters or as return values.
+  #
+  # In LDAP-land, an "entry" is a collection of attributes that are
+  # uniquely and globally identified by a DN ("Distinguished Name").
+  # Attributes are identified by short, descriptive words or phrases.
+  # Although a directory is
+  # free to implement any attribute name, most of them follow rigorous
+  # standards so that the range of commonly-encountered attribute
+  # names is not large.
+  #
+  # An attribute name is case-insensitive. Most directories also
+  # restrict the range of characters allowed in attribute names.
+  # To simplify handling attribute names, Net::LDAP::Entry
+  # internally converts them to a standard format. Therefore, the
+  # methods which take attribute names can take Strings or Synmbols,
+  # and work correctly regardless of case or capitalization.
+  #
+  # An attribute consists of zero or more data items called
+  # <i>values.</i> An entry is the combination of a unique DN, a set of attribute
+  # names, and a (possibly-empty) array of values for each attribute.
+  #
+  # Class Net::LDAP::Entry provides convenience methods for dealing
+  # with LDAP entries.
+  #
   class Entry
 
-    def initialize dn = nil
+    # This constructor is not generally called by user code.
+    def initialize dn = nil # :nodoc:
       @myhash = Hash.new {|k,v| k[v] = [] }
       @myhash[:dn] = [dn]
     end
 
 
-    def []= name, value
+    def []= name, value # :nodoc:
       sym = name.to_s.downcase.intern
       @myhash[sym] = value
     end
@@ -52,22 +80,33 @@ class LDAP
     # because this one and not the other one gets called
     # in formulations like entry["CN"] << cn.
     #
-    def [] name
+    def [] name # :nodoc:
       name = name.to_s.downcase.intern unless name.is_a?(Symbol)
       @myhash[name]
     end
 
+    # Returns the dn of the Entry as a String.
     def dn
       self[:dn][0]
     end
 
+    # Returns an array of the attribute names present in the Entry.
     def attribute_names
       @myhash.keys
     end
 
+    # Accesses each of the attributes present in the Entry.
+    # Calls a user-supplied block with each attribute in turn,
+    # passing two arguments to the block: a Symbol giving
+    # the name of the attribute, and a (possibly empty)
+    # Array of data values.
+    #
     def each
       if block_given?
-        attribute_names.each {|a| yield a, self[a] }
+        attribute_names.each {|a|
+          attr_name,values = a,self[a]
+          yield attr_name, values
+        }
       end
     end