undeprecated Net::LDAP#modify.

ChangeLog

@@ -1,5 +1,9 @@
 = Net::LDAP Changelog
 
+== Net::LDAP 0.0.4: August xx, 2006
+* Undeprecated Net::LDAP#modify. Thanks to Justin Forder for
+  providing the rationale for this.
+
 == Net::LDAP 0.0.3: July 26, 2006
 * Added simple TLS encryption.
   Thanks to Garett Shulman for suggestions and for helping test.

Release-Announcement

@@ -1,40 +1,16 @@
-We're pleased to announce version 0.0.3 of Net::LDAP, the first
+We're pleased to announce version 0.0.4 of Net::LDAP, the first
-pure-Ruby LDAP library. Net::LDAP intends to be a feature-complete
+pure-Ruby LDAP library.
-LDAP client which can access as much as possible of the functionality
+
-of the most-used LDAP server implementations. This library does
+This version un-deprecates Net::LDAP#modify, which can be useful with
-not wrap any existing native-code LDAP libraries, creates no
+LDAP servers that observe non-standard transactional and concurrency
+semantics in LDAP Modify operations. Note: this is a documentation change,
+not a code change.
+
+Net::LDAP is a feature-complete LDAP client which can access as much as
+possible of the functionality of the most-used LDAP server implementations.
+This library does not wrap any existing native-code LDAP libraries, creates no
 Ruby extensions, and has no dependencies external to Ruby.
 
-Version 0.0.3 adds support for encrypted communications to LDAP servers.
-There is a new optional parameter for Net::LDAP#new and Net::LDAP#open
-that allows you to specify encryption characteristics. Here's a quick
-example:
-
-    require 'net/ldap'
-    ldap = Net::LDAP.new(
-      :host => "an_ip_address",
-      :port => 636,
-      :auth => {:method => :simple, :username => "mickey", :password => "mouse" },
-      :encryption => {:method => :simple_tls}
-    )
-    ldap.bind or raise "bind failed"
-    ldap.search( ... )
-    # etc, etc.
-
-This release supports simple TLS encryption with no client or server
-validation. Future versions will add support for the STARTTLS control,
-and for certificate validation. Additional parameters will appear to
-support these options.
-
-Net::LDAP encryption requires Ruby's openssl library. We're not
-quite sure what happens when this library is present but the underlying
-OpenSSL libraries are missing or not configured appropriately,
-especially on back versions of Ruby. If anyone encounters problems
-using encryption in Net::LDAP, please let us know and give us the
-details of your platform and Ruby build info.
-
-Thanks to Garett Shulman for helping to test the new code.
-
 If anyone wants to contribute suggestions, insights or (especially)
 code, please email me at garbagecat10 .. .. gmail.com.
 

lib/net/ldap.rb

@@ -757,8 +757,6 @@ module Net
     end
 
 
-    # _DEPRECATED_ - Please use #add_attribute, #replace_attribute, or #delete_attribute.
-    #
     # Modifies the attribute values of a particular entry on the LDAP directory.
     # Takes a hash with arguments. Supported arguments are:
     # :dn :: (the full DN of the entry whose attributes are to be modified)
@@ -768,6 +766,9 @@ module Net
     # succeeded or failed, with extended information available by calling
     # #get_operation_result.
     #
+    # Also see #add_attribute, #replace_attribute, or #delete_attribute, which
+    # provide simpler interfaces to this functionality.
+    #
     # The LDAP protocol provides a full and well thought-out set of operations
     # for changing the values of attributes, but they are necessarily somewhat complex
     # and not always intuitive. If these instructions are confusing or incomplete,
@@ -786,14 +787,15 @@ module Net
     # The :add operator will, unsurprisingly, add the specified values to
     # the specified attribute. If the attribute does not already exist,
     # :add will create it. Most LDAP servers will generate an error if you
-    # to add a value that already exists.
+    # try to add a value that already exists.
     #
     # :replace will erase the current value(s) for the specified attribute,
     # if there are any, and replace them with the specified value(s).
     #
     # :delete will remove the specified value(s) from the specified attribute.
     # If you pass nil, an empty string, or an empty array as the value parameter
-    # to a :delete operation, the _entire_ _attribute_ will be deleted.
+    # to a :delete operation, the _entire_ _attribute_ will be deleted, along
+    # with all of its values.
     #
     # For example:
     #
@@ -808,13 +810,14 @@ module Net
     # <i>(This example is contrived since you probably wouldn't add a mail
     # value right before replacing the whole attribute, but it shows that order
     # of execution matters. Also, many LDAP servers won't let you delete SN
-    # because it would be a schema violation.)</i>
+    # because that would be a schema violation.)</i>
     #
     # It's essential to keep in mind that if you specify more than one operation in
     # a call to #modify, most LDAP servers will attempt to perform all of the operations
     # in the order you gave them.
     # This matters because you may specify operations on the
     # same attribute which must be performed in a certain order.
+    #
     # Most LDAP servers will _stop_ processing your modifications if one of them
     # causes an error on the server (such as a schema-constraint violation).
     # If this happens, you will probably get a result code from the server that
@@ -825,6 +828,14 @@ module Net
     # not be "rolled back," resulting in a partial update. This is a limitation
     # of the LDAP protocol, not of Net::LDAP.
     #
+    # The lack of transactional atomicity in LDAP means that you're usually
+    # better off using the convenience methods #add_attribute, #replace_attribute,
+    # and #delete_attribute, which are are wrappers over #modify. However, certain
+    # LDAP servers may provide concurrency semantics, in which the several operations
+    # contained in a single #modify call are not interleaved with other
+    # modification-requests received simultaneously by the server.
+    # It bears repeating that this concurrency does _not_ imply transactional
+    # atomicity, which LDAP does not provide.
     #
     def modify args
       if @open_connection