Javadoc review

spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdn.java

@@ -40,7 +40,7 @@ public class LdapRdn implements Serializable, Comparable {
     private List components = new LinkedList();
 
     /**
-     * Default constructor.
+     * Default constructor. Create an empty, uninitialized LdapRdn.
      */
     public LdapRdn() {
     }
@@ -68,7 +68,9 @@ public class LdapRdn implements Serializable, Comparable {
      * Construct an LdapRdn using the supplied key and value.
      * 
      * @param key
+     *            the attribute name.
      * @param value
+     *            the attribute value.
      */
     public LdapRdn(String key, String value) {
         components.add(new LdapRdnComponent(key, value));
@@ -98,7 +100,7 @@ public class LdapRdn implements Serializable, Comparable {
      * 
      * @return The first LdapRdnComponent of this LdapRdn.
      * @throws IndexOutOfBoundsException
-     *             if no components have been added.
+     *             if there are no components in this Rdn.
      */
     public LdapRdnComponent getComponent() {
         return (LdapRdnComponent) components.get(0);
@@ -109,18 +111,20 @@ public class LdapRdn implements Serializable, Comparable {
      * 
      * @param idx
      *            the 0-based index of the component to get.
-     * @return the LdapRdnComponent at indet <code>idx</code>.
+     * @return the LdapRdnComponent at index <code>idx</code>.
      * @throws IndexOutOfBoundsException
-     *             if no component exists at index <code>idx</code>.
+     *             if there are no components in this Rdn.
      */
     public LdapRdnComponent getComponent(int idx) {
         return (LdapRdnComponent) components.get(idx);
     }
 
     /**
-     * Get a properly rfc2253-encoded String representation to this LdapRdn.
+     * Get a properly rfc2253-encoded String representation of this LdapRdn.
      * 
-     * @return an encoded String corresponding to this LdapRdn.
+     * @return an escaped String corresponding to this LdapRdn.
+     * @throws IndexOutOfBoundsException
+     *             if there are no components in this Rdn.
      */
     public String getLdapEncoded() {
         if (components.size() == 0) {
@@ -170,6 +174,11 @@ public class LdapRdn implements Serializable, Comparable {
         return comparator.compare(this.components, that.components);
     }
 
+    /*
+     * (non-Javadoc)
+     * 
+     * @see java.lang.Object#equals(java.lang.Object)
+     */
     public boolean equals(Object obj) {
         if (obj == null || obj.getClass() != this.getClass()) {
             return false;
@@ -205,7 +214,7 @@ public class LdapRdn implements Serializable, Comparable {
      * 
      * @return the (first) value of this LdapRdn.
      * @throws IndexOutOfBoundsException
-     *             if there is no components in this Rdn.
+     *             if there are no components in this Rdn.
      */
     public String getValue() {
         return getComponent().getValue();
@@ -219,7 +228,7 @@ public class LdapRdn implements Serializable, Comparable {
      * 
      * @return the (first) key of this LdapRdn.
      * @throws IndexOutOfBoundsException
-     *             if there is no components in this Rdn.
+     *             if there are no components in this Rdn.
      */
     public String getKey() {
         return getComponent().getKey();

spring-ldap/src/main/java/org/springframework/ldap/core/LdapRdnComponent.java

@@ -114,9 +114,9 @@ public class LdapRdnComponent implements Comparable, Serializable {
     }
 
     /**
-     * Encode key and value to ldap
+     * Encode key and value to ldap.
      * 
-     * @return The ldap encoded rdn
+     * @return Properly ldap escaped rdn.
      */
     protected String encodeLdap() {
         StringBuffer buff = new StringBuffer(key.length() + value.length() * 2);
@@ -144,6 +144,11 @@ public class LdapRdnComponent implements Comparable, Serializable {
         return encodeLdap();
     }
 
+    /**
+     * Get a String representation of this instance for use in URLs.
+     * 
+     * @return a properly URL encoded representation of this instancs.
+     */
     public String encodeUrl() {
         // Use the URI class to properly URL encode the value.
         try {
@@ -155,13 +160,20 @@ public class LdapRdnComponent implements Comparable, Serializable {
         }
     }
 
-    /**
+    /*
+     * (non-Javadoc)
+     * 
      * @see java.lang.Object#hashCode()
      */
     public int hashCode() {
         return key.hashCode() ^ value.hashCode();
     }
 
+    /*
+     * (non-Javadoc)
+     * 
+     * @see java.lang.Object#equals(java.lang.Object)
+     */
     public boolean equals(Object obj) {
         if (obj != null && obj.getClass() == LdapRdnComponent.class) {
             LdapRdnComponent that = (LdapRdnComponent) obj;

spring-ldap/src/main/java/org/springframework/ldap/core/LdapTemplate.java

@@ -1295,14 +1295,29 @@ public class LdapTemplate implements LdapOperations, InitializingBean {
         }
     }
 
+    /*
+     * (non-Javadoc)
+     * 
+     * @see org.springframework.ldap.core.LdapOperations#lookupContext(javax.naming.Name)
+     */
     public DirContextOperations lookupContext(Name dn) {
         return (DirContextOperations) lookup(dn);
     }
 
+    /*
+     * (non-Javadoc)
+     * 
+     * @see org.springframework.ldap.core.LdapOperations#lookupContext(java.lang.String)
+     */
     public DirContextOperations lookupContext(String dn) {
         return (DirContextOperations) lookup(dn);
     }
 
+    /*
+     * (non-Javadoc)
+     * 
+     * @see org.springframework.ldap.core.LdapOperations#modifyAttributes(org.springframework.ldap.core.DirContextOperations)
+     */
     public void modifyAttributes(DirContextOperations ctx) {
         Name dn = ctx.getDn();
         if (dn != null && ctx.isUpdateMode()) {

spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairCallbackHandler.java

@@ -19,10 +19,11 @@ package org.springframework.ldap.core;
 import javax.naming.NameClassPair;
 
 /**
- * Callback interface used by LdapTemplate's search, list and listBindings
+ * Callback interface used by {@link LdapTemplate} search, list and listBindings
  * methods. Implementations of this interface perform the actual work of
- * extracting results from a single NameClassPair (a NameClassPair,
- * Binding or SearchResult depending on the search operation) returned by an
+ * extracting results from a single <code>NameClassPair</code> (a
+ * <code>NameClassPair</code>, <code>Binding</code> or
+ * <code>SearchResult</code> depending on the search operation) returned by an
  * LDAP seach operation, such as search(), list(), and listBindings().
  * 
  * @author Mattias Arthursson
@@ -33,7 +34,8 @@ public interface NameClassPairCallbackHandler {
      * by a search or list.
      * 
      * @param nameClassPair
-     *            the NameClassPair returned from the NamingEnumeration.
+     *            the NameClassPair returned from the
+     *            <code>NamingEnumeration</code>.
      */
     public void handleNameClassPair(NameClassPair nameClassPair);
 }

spring-ldap/src/main/java/org/springframework/ldap/core/NameClassPairMapper.java

@@ -20,20 +20,22 @@ import javax.naming.NameClassPair;
 import javax.naming.NamingException;
 
 /**
- * Responsible for mapping NameClassPair objects to beans.
+ * Responsible for mapping <code>NameClassPair</code> objects to beans.
  * 
  * @author Mattias Arthursson
  */
 public interface NameClassPairMapper {
     /**
-     * Map NameClassPair to an Object. The supplied NameClassPair is one of the
-     * results from a search operation (search, list or listBindings). Depending
-     * on which search operation is being performed, the NameClassPair might be
-     * a SearchResult, Binding or NameClassPair.
+     * Map <code>NameClassPair</code> to an Object. The supplied
+     * <code>NameClassPair</code> is one of the results from a search
+     * operation (search, list or listBindings). Depending on which search
+     * operation is being performed, the <code>NameClassPair</code> might be a
+     * <code>SearchResult</code>, <code>Binding</code> or
+     * <code>NameClassPair</code>.
      * 
      * @param nameClassPair
-     *            NameClassPair from a search operation.
-     * @return and Object built from the NameClassPair.
+     *            <code>NameClassPair</code> from a search operation.
+     * @return and Object built from the <code>NameClassPair</code>.
      * @throws NamingException
      *             if one is encountered in the operation.
      */

spring-ldap/src/main/java/org/springframework/ldap/core/ObjectRetrievalException.java

@@ -19,8 +19,8 @@ package org.springframework.ldap.core;
 import org.springframework.ldap.NamingException;
 
 /**
- * Thrown by a ContextMapperCallbackHandler when it cannot retrieve an object
- * from the given Binding.
+ * Thrown by a {@link ContextMapperCallbackHandler} when it cannot retrieve an
+ * object from the given <code>Binding</code>.
  * 
  * @author Ulrik Sandberg
  * @since 1.2

spring-ldap/src/main/java/org/springframework/ldap/core/SearchExecutor.java

@@ -41,8 +41,9 @@ public interface SearchExecutor {
      * Execute the actual search.
      * 
      * @param ctx
-     *            the DirContext on which to work.
-     * @return the NamingEnumeration resulting from the search operation.
+     *            the <code>DirContext</code> on which to work.
+     * @return the <code>NamingEnumeration</code> resulting from the search
+     *         operation.
      * @throws NamingException
      *             if the search results in one.
      */