Cleanup of comparators package.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1356950 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java

@@ -28,9 +28,7 @@ import java.util.Comparator;
  * @see #booleanComparator(boolean)
  *
  * @since Commons Collections 3.0
- * @version $Revision$
+ * @version $Id$
- *
- * @author Rodney Waldhoff
  */
 public final class BooleanComparator implements Comparator<Boolean>, Serializable {
 

src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java

@@ -20,24 +20,23 @@ import java.io.Serializable;
 import java.util.Comparator;
 
 /**
- * A {@link Comparator Comparator} that compares 
+ * A {@link Comparator Comparator} that compares {@link Comparable Comparable}
- * {@link Comparable Comparable} objects.
+ * objects.
- * <p />
+ * <p>
- * This Comparator is useful, for example,
+ * This Comparator is useful, for example, for enforcing the natural order in
- * for enforcing the natural order in custom implementations
+ * custom implementations of {@link SortedSet} and {@link SortedMap}.
- * of SortedSet and SortedMap.
+ * <p>
- * <p />
+ * Note: In the 2.0 and 2.1 releases of Commons Collections, this class would
- * Note: In the 2.0 and 2.1 releases of Commons Collections, 
+ * throw a {@link ClassCastException} if either of the arguments to
- * this class would throw a {@link ClassCastException} if
+ * {@link #compare(Object, Object) compare} were <code>null</code>, not
- * either of the arguments to {@link #compare(Object, Object) compare}
+ * {@link Comparable Comparable}, or for which
- * were <code>null</code>, not {@link Comparable Comparable},
+ * {@link Comparable#compareTo(Object) compareTo} gave inconsistent results.
- * or for which {@link Comparable#compareTo(Object) compareTo} gave
+ * This is no longer the case. See {@link #compare(Object, Object) compare} for
- * inconsistent results.  This is no longer the case.  See
+ * details.
- * {@link #compare(Object, Object) compare} for details.
+ * 
- *
  * @since Commons Collections 2.0
- * @version $Revision$
+ * @version $Id$
- *
+ * 
  * @see java.util.Collections#reverseOrder()
  */
 public class ComparableComparator<E extends Comparable<? super E>> implements Comparator<E>, Serializable {
@@ -57,6 +56,7 @@ public class ComparableComparator<E extends Comparable<? super E>> implements Co
      * instead of constructing a new instance to reduce allocation and GC overhead
      * when multiple comparable comparators may be used in the same VM.
      * 
+     * @param <E>  the element type
      * @return the singleton ComparableComparator
      */
     @SuppressWarnings("unchecked")
@@ -83,9 +83,9 @@ public class ComparableComparator<E extends Comparable<? super E>> implements Co
      * @param obj1  the first object to compare
      * @param obj2  the second object to compare
      * @return negative if obj1 is less, positive if greater, zero if equal
-     * @throws NullPointerException when <i>obj1</i> is <code>null</code>, 
+     * @throws NullPointerException if <i>obj1</i> is <code>null</code>, 
      *         or when <code>((Comparable)obj1).compareTo(obj2)</code> does
-     * @throws ClassCastException when <i>obj1</i> is not a <code>Comparable</code>,
+     * @throws ClassCastException if <i>obj1</i> is not a <code>Comparable</code>,
      *         or when <code>((Comparable)obj1).compareTo(obj2)</code> does
      */
     public int compare(E obj1, E obj2) {
@@ -106,18 +106,16 @@ public class ComparableComparator<E extends Comparable<? super E>> implements Co
     }
 
     /**
-     * Returns <code>true</code> iff <i>that</i> Object is 
+     * Returns {@code true} iff <i>that</i> Object is is a {@link Comparator Comparator}
-     * is a {@link Comparator Comparator} whose ordering is 
+     * whose ordering is known to be equivalent to mine.
-     * known to be equivalent to mine.
      * <p>
-     * This implementation returns <code>true</code>
+     * This implementation returns {@code true} iff
-     * iff <code><i>object</i>.{@link Object#getClass() getClass()}</code>
+     * <code><i>object</i>.{@link Object#getClass() getClass()}</code> equals
-     * equals <code>this.getClass()</code>.
+     * <code>this.getClass()</code>. Subclasses may want to override this behavior to remain
-     * Subclasses may want to override this behavior to remain consistent
+     * consistent with the {@link Comparator#equals(Object)} contract.
-     * with the {@link Comparator#equals(Object)} contract.
      * 
      * @param object  the object to compare with
-     * @return true if equal
+     * @return {@code true} if equal
      * @since Commons Collections 3.0
      */
     @Override

src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java

@@ -24,35 +24,28 @@ import java.util.Iterator;
 import java.util.List;
 
 /**
- * <p>A ComparatorChain is a Comparator that wraps one or
+ * A ComparatorChain is a Comparator that wraps one or more Comparators in
- * more Comparators in sequence.  The ComparatorChain
+ * sequence. The ComparatorChain calls each Comparator in sequence until either
- * calls each Comparator in sequence until either 1)
+ * 1) any single Comparator returns a non-zero result (and that result is then
- * any single Comparator returns a non-zero result
+ * returned), or 2) the ComparatorChain is exhausted (and zero is returned).
- * (and that result is then returned),
+ * This type of sorting is very similar to multi-column sorting in SQL, and this
- * or 2) the ComparatorChain is exhausted (and zero is
+ * class allows Java classes to emulate that kind of behaviour when sorting a
- * returned).  This type of sorting is very similar
+ * List.
- * to multi-column sorting in SQL, and this class
+ * <p>
- * allows Java classes to emulate that kind of behaviour
+ * To further facilitate SQL-like sorting, the order of any single Comparator in
- * when sorting a List.</p>
+ * the list can be reversed.
- *
+ * <p>
- * <p>To further facilitate SQL-like sorting, the order of
+ * Calling a method that adds new Comparators or changes the ascend/descend sort
- * any single Comparator in the list can be reversed.</p>
+ * <i>after compare(Object, Object) has been called</i> will result in an
- *
+ * UnsupportedOperationException. However, <i>take care</i> to not alter the
- * <p>Calling a method that adds new Comparators or
+ * underlying List of Comparators or the BitSet that defines the sort order.
- * changes the ascend/descend sort <i>after compare(Object,
+ * <p>
- * Object) has been called</i> will result in an
+ * Instances of ComparatorChain are not synchronized. The class is not
- * UnsupportedOperationException.  However, <i>take care</i>
+ * thread-safe at construction time, but it <i>is</i> thread-safe to perform
- * to not alter the underlying List of Comparators
+ * multiple comparisons after all the setup operations are complete.
- * or the BitSet that defines the sort order.</p>
+ * 
- *
- * <p>Instances of ComparatorChain are not synchronized.
- * The class is not thread-safe at construction time, but
- * it <i>is</i> thread-safe to perform multiple comparisons
- * after all the setup operations are complete.</p>
- *
  * @since Commons Collections 2.0
- * @author Morgan Delagrange
+ * @version $Id$
- * @version $Revision$
  */
 public class ComparatorChain<E> implements Comparator<E>, Serializable {
 
@@ -237,13 +230,23 @@ public class ComparatorChain<E> implements Comparator<E>, Serializable {
         return isLocked;
     }
 
-    // throw an exception if the ComparatorChain is locked
+    /**
+     * Throws an exception if the {@link ComparatorChain} is locked.
+     * 
+     * @throws UnsupportedOperationException if the {@link ComparatorChain} is locked
+     */
     private void checkLocked() {
         if (isLocked == true) {
-            throw new UnsupportedOperationException("Comparator ordering cannot be changed after the first comparison is performed");
+            throw new UnsupportedOperationException(
+                    "Comparator ordering cannot be changed after the first comparison is performed");
         }
     }
 
+    /**
+     * Throws an exception if the {@link ComparatorChain} is empty.
+     * 
+     * @throws UnsupportedOperationException if the {@link ComparatorChain} is empty
+     */
     private void checkChainIntegrity() {
         if (comparatorChain.size() == 0) {
             throw new UnsupportedOperationException("ComparatorChains must contain at least one Comparator");

src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java

@@ -41,17 +41,13 @@ import java.util.Map;
  * multiple comparisons  after all the setup operations are complete.
  *
  * @since Commons Collections 3.0
- * @version $Revision$
+ * @version $Id$
- *
- * @author David Leppik
- * @author Stephen Colebourne
- * @author Janek Bogucki
  */
 public class FixedOrderComparator<T> implements Comparator<T> {
 
     /**
      * Unknown object behavior enum.
-     * @since Commons Collections 5
+     * @since Commons Collections 4.0
      */
     public static enum UnknownObjectBehavior {
         BEFORE, AFTER, EXCEPTION;

src/main/java/org/apache/commons/collections/comparators/NullComparator.java

@@ -26,9 +26,7 @@ import org.apache.commons.collections.ComparatorUtils;
  * other objects.
  *
  * @since Commons Collections 2.0
- * @version $Revision$
+ * @version $Id$
- *
- * @author Michael A. Smith
  */
 public class NullComparator<E> implements Comparator<E>, Serializable {
 

src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java

@@ -26,9 +26,7 @@ import org.apache.commons.collections.ComparatorUtils;
  * to its {@link #compare(Object, Object) compare} method.
  *
  * @since Commons Collections 2.0
- * @version $Revision$
+ * @version $Id$
- *
- * @author Michael A. Smith
  *
  * @see java.util.Collections#reverseOrder()
  */

src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java

@@ -26,8 +26,8 @@ import org.apache.commons.collections.Transformer;
  * return value from the transform operation will be passed to the decorated
  * {@link Comparator#compare(Object,Object) compare} method.
  *
- * @since Commons Collections 2.0 (?)
+ * @since Commons Collections 2.1
- * @version $Revision$
+ * @version $Id$
  *
  * @see org.apache.commons.collections.Transformer
  * @see org.apache.commons.collections.comparators.ComparableComparator

src/main/java/org/apache/commons/collections/comparators/package-info.java

@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * This package contains implementations of the
+ * {@link java.util.Comparator Comparator} interface.
+ * <p>
+ * You may also consider using 
+ * {@link org.apache.commons.collections.ComparatorUtils ComparatorUtils},
+ * which is a single class that uses static methods to construct instances
+ * of the classes in this package.
+ * 
+ * @version $Id$
+ */
+package org.apache.commons.collections.comparators;

src/main/java/org/apache/commons/collections/comparators/package.html

@@ -1,27 +0,0 @@
-<!-- $Id$ -->
- <!--
-   Licensed to the Apache Software Foundation (ASF) under one or more
-  contributor license agreements.  See the NOTICE file distributed with
-  this work for additional information regarding copyright ownership.
-  The ASF licenses this file to You under the Apache License, Version 2.0
-  (the "License"); you may not use this file except in compliance with
-  the License.  You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-  -->
-<BODY>
-<p>
-This package contains implementations of the
-{@link java.util.Comparator Comparator} interface.
-<p>
-You may also consider using 
-{@link org.apache.commons.collections.ComparatorUtils ComparatorUtils},
-which is a single class that uses static methods to construct instances
-of the classes in this package.
-</BODY>