+ Adds comments (and some layouting)

lib/net/ldap/core_ext/bignum.rb

@@ -4,9 +4,9 @@ module Net
       module Bignum
 
         def to_ber
-          # NOTE: Array#pack's 'w' is a BER _compressed_ integer. We need uncompressed
+          # NOTE: Array#pack's 'w' is a BER _compressed_ integer. We need
-          # BER integers, so we're not using that.
+          # uncompressed BER integers, so we're not using that. See also:
-          # See also: http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/228864
+          # http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/228864
           result = []
 
           n = self

lib/net/ldap/core_ext/fixnum.rb

@@ -36,23 +36,33 @@ module Net
         end
 
         #--
-        # Called internally to BER-encode the length and content bytes of a Fixnum.
+        # Called internally to BER-encode the length and content bytes of a 
-        # The caller will prepend the tag byte.
+        # Fixnum. The caller will prepend the tag byte.
+        #
         MAX_SIZE = 0.size
         def to_ber_internal
+          # CAUTION: Bit twiddling ahead. You might want to shield your eyes 
+          # or something. 
+          
+          # Looks for the first byte in the fixnum that is not all zeroes. It
+          # does this by masking one byte after another, checking the result
+          # for bits that are left on. 
           size = MAX_SIZE
           while size>1
-              break if (self & (0xff << (size-1)*8)) > 0 
+            break if (self & (0xff << (size-1)*8)) > 0 
-              size -= 1
+            size -= 1
           end
           
+          # Store the size of the fixnum in the result
           result = [size]
 
+          # Appends bytes to result, starting with higher orders first.
+          # Extraction of bytes is done by right shifting the original fixnum
+          # by an amount and then masking that with 0xff.
           while size>0
-              # right shift size-1 bytes, mask with 0xff 
+            # right shift size-1 bytes, mask with 0xff 
-              result << ((self >> ((size-1)*8)) & 0xff)
+            result << ((self >> ((size-1)*8)) & 0xff)
-
+            size -= 1
-              size -= 1
           end
 
           result.pack('C*')

lib/net/ldap/entry.rb

@@ -27,51 +27,49 @@ module Net
 class LDAP
 
 
-  # Objects of this class represent individual entries in an LDAP
+  # Objects of this class represent individual entries in an LDAP directory.
-  # directory. User code generally does not instantiate this class.
+  # User code generally does not instantiate this class. Net::LDAP#search
-  # Net::LDAP#search provides objects of this class to user code,
+  # provides objects of this class to user code, either as block parameters or
-  # either as block parameters or as return values.
+  # as return values.
   #
-  # In LDAP-land, an "entry" is a collection of attributes that are
+  # In LDAP-land, an "entry" is a collection of attributes that are uniquely
-  # uniquely and globally identified by a DN ("Distinguished Name").
+  # and globally identified by a DN ("Distinguished Name"). Attributes are
-  # Attributes are identified by short, descriptive words or phrases.
+  # identified by short, descriptive words or phrases. Although a directory is
-  # Although a directory is
   # free to implement any attribute name, most of them follow rigorous
-  # standards so that the range of commonly-encountered attribute
+  # standards so that the range of commonly-encountered attribute names is not
-  # names is not large.
+  # large.
   #
-  # An attribute name is case-insensitive. Most directories also
+  # An attribute name is case-insensitive. Most directories also restrict the
-  # restrict the range of characters allowed in attribute names.
+  # range of characters allowed in attribute names. To simplify handling
-  # To simplify handling attribute names, Net::LDAP::Entry
+  # attribute names, Net::LDAP::Entry internally converts them to a standard
-  # internally converts them to a standard format. Therefore, the
+  # format. Therefore, the methods which take attribute names can take Strings
-  # methods which take attribute names can take Strings or Symbols,
+  # or Symbols, and work correctly regardless of case or capitalization.
-  # and work correctly regardless of case or capitalization.
   #
-  # An attribute consists of zero or more data items called
+  # An attribute consists of zero or more data items called <i>values.</i> An
-  # <i>values.</i> An entry is the combination of a unique DN, a set of attribute
+  # entry is the combination of a unique DN, a set of attribute names, and a
-  # names, and a (possibly-empty) array of values for each attribute.
+  # (possibly-empty) array of values for each attribute.
   #
-  # Class Net::LDAP::Entry provides convenience methods for dealing
+  # Class Net::LDAP::Entry provides convenience methods for dealing with LDAP
-  # with LDAP entries.
+  # entries. In addition to the methods documented below, you may access
-  # In addition to the methods documented below, you may access individual
+  # individual attributes of an entry simply by giving the attribute name as
-  # attributes of an entry simply by giving the attribute name as
   # the name of a method call. For example:
-  #  ldap.search( ... ) do |entry|
+  #
-  #    puts "Common name: #{entry.cn}"
+  #   ldap.search( ... ) do |entry|
-  #    puts "Email addresses:"
+  #     puts "Common name: #{entry.cn}"
-  #      entry.mail.each {|ma| puts ma}
+  #     puts "Email addresses:"
-  #  end
+  #     entry.mail.each {|ma| puts ma}
-  # If you use this technique to access an attribute that is not present
+  #   end
-  # in a particular Entry object, a NoMethodError exception will be raised.
+  #
+  # If you use this technique to access an attribute that is not present in a
+  # particular Entry object, a NoMethodError exception will be raised.
   #
   #--
-  # Ugly problem to fix someday: We key off the internal hash with
+  # Ugly problem to fix someday: We key off the internal hash with a canonical
-  # a canonical form of the attribute name: convert to a string,
+  # form of the attribute name: convert to a string, downcase, then take the
-  # downcase, then take the symbol. Unfortunately we do this in
+  # symbol. Unfortunately we do this in at least three places. Should do it in
-  # at least three places. Should do it in ONE place.
+  # ONE place.
+  #
   class Entry
-
-
     # This constructor is not generally called by user code.
     #--
     # Originally, myhash took a block so we wouldn't have to