From 01655058b0e85b85d4eabfae4be9083ec7557985 Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sun, 20 Oct 2024 08:31:59 -0400 Subject: [PATCH] Javadoc - Close HTML tags - Use longer lines - Whitespace before tags - Remove dead inline comments = Add missing paragraph tags --- .../commons/collections4/ClosureUtils.java | 4 ++ .../commons/collections4/CollectionUtils.java | 5 +-- .../collections4/EnumerationUtils.java | 1 + .../commons/collections4/FactoryUtils.java | 1 + .../commons/collections4/FluentIterable.java | 12 ++++++ .../commons/collections4/IterableGet.java | 1 + .../commons/collections4/IteratorUtils.java | 2 - .../commons/collections4/ListUtils.java | 40 +++++++++++++++---- .../commons/collections4/ListValuedMap.java | 2 + .../commons/collections4/MapIterator.java | 1 + .../apache/commons/collections4/MultiMap.java | 10 +++++ .../commons/collections4/MultiMapUtils.java | 4 ++ .../apache/commons/collections4/MultiSet.java | 10 +++++ .../commons/collections4/MultiSetUtils.java | 3 +- .../commons/collections4/MultiValuedMap.java | 2 - .../commons/collections4/OrderedBidiMap.java | 3 ++ .../commons/collections4/OrderedMap.java | 1 + .../commons/collections4/PredicateUtils.java | 4 +- .../commons/collections4/QueueUtils.java | 8 +++- .../apache/commons/collections4/SetUtils.java | 1 + .../commons/collections4/SortedBidiMap.java | 3 ++ .../commons/collections4/SplitMapUtils.java | 1 + .../collections4/TransformerUtils.java | 2 + .../org/apache/commons/collections4/Trie.java | 21 +++++----- .../commons/collections4/Unmodifiable.java | 2 + 25 files changed, 113 insertions(+), 31 deletions(-) diff --git a/src/main/java/org/apache/commons/collections4/ClosureUtils.java b/src/main/java/org/apache/commons/collections4/ClosureUtils.java index def04ea9c9..fe190eb86d 100644 --- a/src/main/java/org/apache/commons/collections4/ClosureUtils.java +++ b/src/main/java/org/apache/commons/collections4/ClosureUtils.java @@ -253,6 +253,7 @@ public static Closure nopClosure() { * closure is called. The default closure is set in the map with a * null key. The ordering is that of the iterator() method on the entryset * collection of the map. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * @@ -275,6 +276,7 @@ public static Closure switchClosure(final Map, Closure> p * The closure at array location 0 is called if the predicate at array * location 0 returned true. Each predicate is evaluated * until one returns true. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * @@ -299,6 +301,7 @@ public static Closure switchClosure(final Predicate[] predicat * location 0 returned true. Each predicate is evaluated * until one returns true. If no predicates evaluate to true, the default * closure is called. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * @@ -325,6 +328,7 @@ public static Closure switchClosure(final Predicate[] predicat * is called if the input object equals the key. If there is no match, the * default closure is called. The default closure is set in the map * using a null key. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * diff --git a/src/main/java/org/apache/commons/collections4/CollectionUtils.java b/src/main/java/org/apache/commons/collections4/CollectionUtils.java index 3aed6feae5..49d7cf38a0 100644 --- a/src/main/java/org/apache/commons/collections4/CollectionUtils.java +++ b/src/main/java/org/apache/commons/collections4/CollectionUtils.java @@ -225,6 +225,7 @@ public void setCardinality(final O obj, final int count) { * @since 4.5.0 */ public static final int INDEX_NOT_FOUND = -1; + /** * Default prefix used while converting an Iterator to its String representation. * @@ -461,11 +462,9 @@ public static List collate(final Iterable a, final Iterable< */ public static List collate(final Iterable iterableA, final Iterable iterableB, final Comparator comparator, final boolean includeDuplicates) { - Objects.requireNonNull(iterableA, "iterableA"); Objects.requireNonNull(iterableB, "iterableB"); Objects.requireNonNull(comparator, "comparator"); - // if both Iterables are a Collection, we can estimate the size final int totalSize = iterableA instanceof Collection && iterableB instanceof Collection ? Math.max(1, ((Collection) iterableA).size() + ((Collection) iterableB).size()) : 10; @@ -475,7 +474,6 @@ public static List collate(final Iterable iterableA, final I return IteratorUtils.toList(iterator, totalSize); } final ArrayList mergedList = new ArrayList<>(totalSize); - O lastItem = null; while (iterator.hasNext()) { final O item = iterator.next(); @@ -484,7 +482,6 @@ public static List collate(final Iterable iterableA, final I } lastItem = item; } - mergedList.trimToSize(); return mergedList; } diff --git a/src/main/java/org/apache/commons/collections4/EnumerationUtils.java b/src/main/java/org/apache/commons/collections4/EnumerationUtils.java index 7df8c409e0..b6d27a36dd 100644 --- a/src/main/java/org/apache/commons/collections4/EnumerationUtils.java +++ b/src/main/java/org/apache/commons/collections4/EnumerationUtils.java @@ -50,6 +50,7 @@ public static Iterable asIterable(final Enumeration enumeration) { *

* The Enumeration is advanced to {@code index} (or to the end, if * {@code index} exceeds the number of entries) as a side effect of this method. + *

* * @param e the enumeration to get a value from * @param index the index to get diff --git a/src/main/java/org/apache/commons/collections4/FactoryUtils.java b/src/main/java/org/apache/commons/collections4/FactoryUtils.java index 36d5679448..06f3187f27 100644 --- a/src/main/java/org/apache/commons/collections4/FactoryUtils.java +++ b/src/main/java/org/apache/commons/collections4/FactoryUtils.java @@ -34,6 +34,7 @@ *

* Since v4.1 only factories which are considered to be safe are * Serializable. Factories considered to be unsafe for serialization are: + *

*
    *
  • Prototype *
  • Instantiate diff --git a/src/main/java/org/apache/commons/collections4/FluentIterable.java b/src/main/java/org/apache/commons/collections4/FluentIterable.java index c985d7e575..c58182afb6 100644 --- a/src/main/java/org/apache/commons/collections4/FluentIterable.java +++ b/src/main/java/org/apache/commons/collections4/FluentIterable.java @@ -84,6 +84,7 @@ public static FluentIterable empty() { *

    * The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. + *

    * * @param the element type * @param iterable the iterable to wrap into a FluentIterable, may not be null @@ -102,6 +103,7 @@ public static FluentIterable of(final Iterable iterable) { * Creates a new FluentIterable of the single provided element. *

    * The returned iterable's iterator does not support {@code remove()}. + *

    * * @param the element type * @param singleton the singleton element @@ -115,6 +117,7 @@ public static FluentIterable of(final T singleton) { * Creates a new FluentIterable from the provided elements. *

    * The returned iterable's iterator does not support {@code remove()}. + *

    * * @param the element type * @param elements the elements to be contained in the FluentIterable @@ -147,6 +150,7 @@ private FluentIterable(final Iterable iterable) { * provided predicate. *

    * A {@code null} or empty iterable returns true. + *

    * * @param predicate the predicate to use, may not be null * @return true if all elements contained in this iterable match the predicate, @@ -161,6 +165,7 @@ public boolean allMatch(final Predicate predicate) { * Checks if this iterable contains any element matching the provided predicate. *

    * A {@code null} or empty iterable returns false. + *

    * * @param predicate the predicate to use, may not be null * @return true if at least one element contained in this iterable matches the predicate, @@ -211,6 +216,7 @@ public Enumeration asEnumeration() { * elements of the current and provided iterable in natural order. *

    * Example: natural ordering + *

    *
      *
    • this contains elements [1, 3, 5, 7] *
    • other contains elements [2, 4, 6, 8] @@ -218,6 +224,7 @@ public Enumeration asEnumeration() { *

      * The returned iterable will traverse the elements in the following * order: [1, 2, 3, 4, 5, 6, 7, 8] + *

      * * @param other the other iterable to collate, may not be null * @return a new iterable, collating this iterable with the other in natural order @@ -234,6 +241,7 @@ public FluentIterable collate(final Iterable other) { * ordering defined by a comparator. *

      * Example: descending order + *

      *
        *
      • this contains elements [7, 5, 3, 1] *
      • other contains elements [8, 6, 4, 2] @@ -241,6 +249,7 @@ public FluentIterable collate(final Iterable other) { *

        * The returned iterable will traverse the elements in the following * order: [8, 7, 6, 5, 4, 3, 2, 1] + *

        * * @param comparator the comparator to define an ordering, may be null, * in which case natural ordering will be used @@ -282,10 +291,12 @@ public void copyInto(final Collection collection) { * to the originating iterables and/or iterators. *

        * Calling this method is equivalent to: + *

        * 
              *   FluentIterable<E> someIterable = ...;
      *   FluentIterable.of(someIterable.toList());
      *
        + *

        * * @return a new iterable with the same contents as this iterable */ @@ -416,6 +427,7 @@ public E[] toArray(final Class arrayClass) { * by traversing its iterator. *

        * The returned list is guaranteed to be mutable. + *

        * * @return a list of the iterable contents */ diff --git a/src/main/java/org/apache/commons/collections4/IterableGet.java b/src/main/java/org/apache/commons/collections4/IterableGet.java index 39b7bcab79..4189821bfd 100644 --- a/src/main/java/org/apache/commons/collections4/IterableGet.java +++ b/src/main/java/org/apache/commons/collections4/IterableGet.java @@ -31,6 +31,7 @@ public interface IterableGet extends Get { *

        * A map iterator is an efficient way of iterating over maps. * There is no need to access the entry set or use Map Entry objects. + *

        * 
              * IterableMap<String,Integer> map = new HashedMap<String,Integer>();
      * MapIterator<String,Integer> it = map.mapIterator();
diff --git a/src/main/java/org/apache/commons/collections4/IteratorUtils.java b/src/main/java/org/apache/commons/collections4/IteratorUtils.java
index 4bf0829294..1b62492046 100644
--- a/src/main/java/org/apache/commons/collections4/IteratorUtils.java
+++ b/src/main/java/org/apache/commons/collections4/IteratorUtils.java
@@ -536,7 +536,6 @@ public static  Iterator collatedIterator(final Comparator compa
         return new CollatingIterator<>(comp, iterators);
     }
 
-    // Collated
     /**
      * Gets an iterator that provides an ordered iteration over the elements
      * contained in a collection of ordered {@link Iterator}s.
@@ -1070,7 +1069,6 @@ public static NodeListIterator nodeListIterator(final NodeList nodeList) {
         return new NodeListIterator(Objects.requireNonNull(nodeList, "nodeList"));
     }
 
-    // Object Graph
     /**
      * Gets an iterator that operates over an object graph.
      * 
        
diff --git a/src/main/java/org/apache/commons/collections4/ListUtils.java b/src/main/java/org/apache/commons/collections4/ListUtils.java
index 6a02430114..0aeb413053 100644
--- a/src/main/java/org/apache/commons/collections4/ListUtils.java
+++ b/src/main/java/org/apache/commons/collections4/ListUtils.java
@@ -42,6 +42,7 @@
  * @since 1.0
  */
 public class ListUtils {
+
     /**
      * A simple wrapper to use a CharSequence as List.
      */
@@ -178,6 +179,7 @@ public static  List fixedSizeList(final List list) {
      * 
        
      * Shorthand for {@code list.get(0)}
      * 
        
+     *
      * @param  The list type.
      * @param list The list.
      * @return the first element of a list.
@@ -193,6 +195,7 @@ public static  T getFirst(final List list) {
      * 
        
      * Shorthand for {@code list.get(list.size() - 1)}
      * 
        
+     *
      * @param  The list type.
      * @param list The list.
      * @return the last element of a list.
@@ -210,6 +213,7 @@ public static  T getLast(final List list) {
      * This method is useful for implementing {@code List} when you cannot
      * extend AbstractList. The method takes Collection instances to enable other
      * collection types to use the List implementation algorithm.
+     * 
        
      *
      * @see java.util.List#hashCode()
      * @param list  the list to generate the hashCode for, may be null
@@ -232,6 +236,7 @@ public static int hashCodeForList(final Collection list) {
      * 
        
      * If the input List or predicate is null, or no element of the List
      * matches the predicate, -1 is returned.
+     * 
        
      *
      * @param   the element type
      * @param list the List to search, may be null
@@ -288,8 +293,10 @@ public static  List intersection(final List list1, final List
      * This method is useful for implementing {@code List} when you cannot
      * extend AbstractList. The method takes Collection instances to enable other
      * collection types to use the List implementation algorithm.
+     * 
        
      * 
        
      * The relevant text (slightly paraphrased as this is a static method) is:
+     * 
        
      * 
        
      * Compares the two list objects for equality.  Returns
      * {@code true} if and only if both
@@ -301,9 +308,10 @@ public static  List intersection(final List list1, final List
      * definition ensures that the equals method works properly across
      * different implementations of the {@code List} interface.
      * 
        
-     *
+     * 
        
      * Note: The behavior of this method is undefined if the lists are
      * modified during the equals comparison.
+     * 
        
      *
      * @see java.util.List
      * @param list1  the first list, may be null
@@ -339,9 +347,10 @@ public static boolean isEqualList(final Collection list1, final Collection
      * When the index passed to the returned list's {@link List#get(int) get}
      * method is greater than the list's size, then the factory will be used
      * to create a new object and that object will be inserted at that index.
+     * 
        
      * 
        
      * For instance:
-     *
+     * 
        
      * 
              * Factory<Date> factory = new Factory<Date>() {
      *     public Date create() {
@@ -351,11 +360,12 @@ public static boolean isEqualList(final Collection list1, final Collection
      * List<Date> lazy = ListUtils.lazyList(new ArrayList<Date>(), factory);
      * Date date = lazy.get(3);
      * 
        
-     *
+     * 
        
      * After the above code is executed, {@code date} will refer to
      * a new {@code Date} instance. Furthermore, that {@code Date}
      * instance is the fourth element in the list.  The first, second,
      * and third element are all set to {@code null}.
+     * 
        
      *
      * @param  the element type
      * @param list  the list to make lazy, must not be null
@@ -373,20 +383,22 @@ public static  List lazyList(final List list, final Factory
      * 
        
      * For instance:
-     *
+     * 
        
      * 
              * List<Integer> hours = Arrays.asList(7, 5, 8, 2);
      * Transformer<Integer,Date> transformer = input -> LocalDateTime.now().withHour(hours.get(input));
      * List<LocalDateTime> lazy = ListUtils.lazyList(new ArrayList<LocalDateTime>(), transformer);
      * Date date = lazy.get(3);
      * 
        
-     *
+     * 
        
      * After the above code is executed, {@code date} will refer to
      * a new {@code Date} instance. Furthermore, that {@code Date}
      * instance is the fourth element in the list.  The first, second,
      * and third element are all set to {@code null}.
+     * 
        
      *
      * @param  the element type
      * @param list  the list to make lazy, must not be null
@@ -403,6 +415,7 @@ public static  List lazyList(final List list, final Transformer
      * This is a convenience method for using {@link #longestCommonSubsequence(List, List)}
      * with {@link CharSequence} instances.
+     * 
        
      *
      * @param charSequenceA  the first sequence
      * @param charSequenceB  the second sequence
@@ -471,8 +484,10 @@ public static  List longestCommonSubsequence(final List listA, final Li
      * source list. The inner lists are sublist views of the original list,
      * produced on demand using {@link List#subList(int, int)}, and are subject
      * to all the usual caveats about modification as explained in that API.
+     * 
        
      * 
        
      * Adapted from https://github.com/google/guava
+     * 
        
      *
      * @param  the element type
      * @param list  the list to return consecutive sublists of
@@ -497,6 +512,7 @@ public static  List> partition(final List list, final int size) {
      * Trying to add an invalid object results in an IllegalArgumentException.
      * It is important not to use the original list after invoking this method,
      * as it is a backdoor for adding invalid objects.
+     * 
        
      *
      * @param  the element type
      * @param list  the list to predicate, must not be null
@@ -522,6 +538,7 @@ public static  List predicatedList(final List list, final Predicate
      * to the returned list. As a consequence, it is advised to use a collection type for
      * {@code remove} that provides a fast (e.g. O(1)) implementation of
      * {@link Collection#contains(Object)}.
+     * 
        
      *
      * @param   the element type
      * @param collection  the collection from which items are removed (in the returned collection)
@@ -556,6 +573,7 @@ public static  List removeAll(final Collection collection, final Collec
      * to the returned list. As a consequence, it is advised to use a collection type for
      * {@code retain} that provides a fast (e.g. O(1)) implementation of
      * {@link Collection#contains(Object)}.
+     * 
        
      *
      * @param   the element type
      * @param collection  the collection whose contents are the target of the #retailAll operation
@@ -581,6 +599,7 @@ public static  List retainAll(final Collection collection, final Collec
      * predicate into an output list.
      * 
        
      * A {@code null} predicate matches no elements.
+     * 
        
      *
      * @param  the element type
      * @param inputCollection  the collection to get the input from, may not be null
@@ -601,6 +620,7 @@ public static  List select(final Collection inputCollection,
      * predicate into an output collection.
      * 
        
      * If the input predicate is {@code null}, the result is an empty list.
+     * 
        
      *
      * @param  the element type
      * @param inputCollection the collection to get the input from, may not be null
@@ -625,6 +645,7 @@ public static  List selectRejected(final Collection inputColl
      * occurrences of null and list2 only
      * contains one occurrence, then the returned list will still contain
      * one occurrence.
+     * 
        
      *
      * @param  the element type
      * @param list1  the list to subtract from
@@ -662,7 +683,7 @@ public static  List sum(final List list1, final List
      * You must manually synchronize on the returned list's iterator to
      * avoid non-deterministic behavior:
-     *
+     * 
        
      * 
              * List list = ListUtils.synchronizedList(myList);
      * synchronized (list) {
@@ -672,8 +693,9 @@ public static  List sum(final List list1, final List
-     *
+     * 
        
      * This method is just a wrapper for {@link Collections#synchronizedList(List)}.
+     * 
        
      *
      * @param  the element type
      * @param list  the list to synchronize, must not be null
@@ -690,13 +712,16 @@ public static  List synchronizedList(final List list) {
      * This method returns a new list (decorating the specified list) that
      * will transform any new entries added to it.
      * Existing entries in the specified list will not be transformed.
+     * 
        
      * 
        
      * Each object is passed through the transformer as it is added to the
      * List. It is important not to use the original list after invoking this
      * method, as it is a backdoor for adding untransformed objects.
+     * 
        
      * 
        
      * Existing entries in the specified list will not be transformed.
      * If you want that behavior, see {@link TransformedList#transformedList}.
+     * 
        
      *
      * @param  the element type
      * @param list  the list to predicate, must not be null
@@ -731,6 +756,7 @@ public static  List union(final List list1, final List
      * This method uses the implementation in the decorators subpackage.
+     * 
        
      *
      * @param   the element type
      * @param list  the list to make unmodifiable, must not be null
diff --git a/src/main/java/org/apache/commons/collections4/ListValuedMap.java b/src/main/java/org/apache/commons/collections4/ListValuedMap.java
index 75079bd328..37174ae5a9 100644
--- a/src/main/java/org/apache/commons/collections4/ListValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/ListValuedMap.java
@@ -41,6 +41,7 @@ public interface ListValuedMap extends MultiValuedMap {
      * {@link #containsKey(Object)} returns {@code false}. Changes to the
      * returned list will update the underlying {@code ListValuedMap} and
      * vice-versa.
+     * 
        
      *
      * @param key  the key to retrieve
      * @return the {@code List} of values, implementations should return an
@@ -56,6 +57,7 @@ public interface ListValuedMap extends MultiValuedMap {
      * The returned list may be modifiable, but updates will not be
      * propagated to this list-valued map. In case no mapping was stored for the
      * specified key, an empty, unmodifiable list will be returned.
+     * 
        
      *
      * @param key  the key to remove values from
      * @return the {@code List} of values removed, implementations
diff --git a/src/main/java/org/apache/commons/collections4/MapIterator.java b/src/main/java/org/apache/commons/collections4/MapIterator.java
index 54cd88e76a..c9c76fc9c6 100644
--- a/src/main/java/org/apache/commons/collections4/MapIterator.java
+++ b/src/main/java/org/apache/commons/collections4/MapIterator.java
@@ -88,6 +88,7 @@ public interface MapIterator extends Iterator {
      * Removes the last returned key from the underlying {@code Map} (optional operation).
      * 
        
      * This method can be called once per call to {@code next()}.
+     * 
        
      *
      * @throws UnsupportedOperationException if remove is not supported by the map
      * @throws IllegalStateException if {@code next()} has not yet been called
diff --git a/src/main/java/org/apache/commons/collections4/MultiMap.java b/src/main/java/org/apache/commons/collections4/MultiMap.java
index 1e10fda861..ad6d4fa106 100644
--- a/src/main/java/org/apache/commons/collections4/MultiMap.java
+++ b/src/main/java/org/apache/commons/collections4/MultiMap.java
@@ -57,6 +57,7 @@ public interface MultiMap extends IterableMap {
      * 
        
      * Implementations typically check all collections against all keys for the value.
      * This cannot be mandated due to backwards compatibility of this interface.
+     * 
        
      *
      * @param value  the value to search for
      * @return true if the map contains the value
@@ -72,12 +73,15 @@ public interface MultiMap extends IterableMap {
      * The returned value will implement {@code Collection}. Implementations
      * are free to declare that they return {@code Collection} subclasses
      * such as {@code List} or {@code Set}.
+     * 
        
      * 
        
      * Implementations typically return {@code null} if no values have
      * been mapped to the key, however the implementation may choose to
      * return an empty collection.
+     * 
        
      * 
        
      * Implementations may choose to return a clone of the internal collection.
+     * 
        
      *
      * @param key  the key to retrieve
      * @return the {@code Collection} of values, implementations should
@@ -95,6 +99,7 @@ public interface MultiMap extends IterableMap {
      * Instead, the new value is added to the collection stored against the key.
      * The collection may be a {@code List}, {@code Set} or other
      * collection dependent on implementation.
+     * 
        
      *
      * @param key  the key to store against
      * @param value  the value to add to the collection at the key
@@ -112,6 +117,7 @@ public interface MultiMap extends IterableMap {
      * 
        
      * Implementations typically return {@code null} from a subsequent
      * {@code get(Object)}, however they may choose to return an empty collection.
+     * 
        
      *
      * @param key  the key to remove values from
      * @return the {@code Collection} of values removed, implementations should
@@ -128,10 +134,12 @@ public interface MultiMap extends IterableMap {
      * 
        
      * The item is removed from the collection mapped to the specified key.
      * Other values attached to that key are unaffected.
+     * 
        
      * 
        
      * If the last value for a key is removed, implementations typically
      * return {@code null} from a subsequent {@code get(Object)}, however
      * they may choose to return an empty collection.
+     * 
        
      *
      * @param key  the key to remove from
      * @param item  the item to remove
@@ -148,6 +156,7 @@ public interface MultiMap extends IterableMap {
      * 
        
      * Implementations typically return only the count of keys in the map
      * This cannot be mandated due to backwards compatibility of this interface.
+     * 
        
      *
      * @return the number of key-collection mappings in this map
      */
@@ -160,6 +169,7 @@ public interface MultiMap extends IterableMap {
      * Implementations typically return a collection containing the combination
      * of values from all keys.
      * This cannot be mandated due to backwards compatibility of this interface.
+     * 
        
      *
      * @return a collection view of the values contained in this map
      */
diff --git a/src/main/java/org/apache/commons/collections4/MultiMapUtils.java b/src/main/java/org/apache/commons/collections4/MultiMapUtils.java
index a91372722c..77dee5afe5 100644
--- a/src/main/java/org/apache/commons/collections4/MultiMapUtils.java
+++ b/src/main/java/org/apache/commons/collections4/MultiMapUtils.java
@@ -161,6 +161,7 @@ public static  Set getValuesAsSet(final MultiValuedMap map, final
      * Null-safe check if the specified {@code MultiValuedMap} is empty.
      * 
        
      * If the provided map is null, returns true.
+     * 
        
      *
      * @param map  the map to check, may be null
      * @return true if the map is empty or null
@@ -200,13 +201,16 @@ public static  SetValuedMap newSetValuedHashMap() {
      * specified map) that will transform any new entries added to it. Existing
      * entries in the specified map will not be transformed. If you want that
      * behavior, see {@link TransformedMultiValuedMap#transformedMap}.
+     * 
        
      * 
        
      * Each object is passed through the transformers as it is added to the Map.
      * It is important not to use the original map after invoking this method,
      * as it is a back door for adding untransformed objects.
+     * 
        
      * 
        
      * If there are any elements already in the map being decorated, they are
      * NOT transformed.
+     * 
        
      *
      * @param  the key type
      * @param  the value type
diff --git a/src/main/java/org/apache/commons/collections4/MultiSet.java b/src/main/java/org/apache/commons/collections4/MultiSet.java
index 5096ad5867..122a824ea2 100644
--- a/src/main/java/org/apache/commons/collections4/MultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/MultiSet.java
@@ -39,6 +39,7 @@ public interface MultiSet extends Collection {
      * 
        
      * The {@link MultiSet#entrySet()} method returns a view of the multiset whose elements
      * implement this interface.
+     * 
        
      *
      * @param   the element type
      */
@@ -52,6 +53,7 @@ interface Entry {
          * 
        
          * More formally, two entries {@code e1} and {@code e2} represent
          * the same mapping if
+         * 
        
          * 
                  *     (e1.getElement()==null ? e2.getElement()==null
          *                            : e1.getElement().equals(e2.getElement())) &&
@@ -98,6 +100,7 @@ interface Entry {
      * If the object is already in the {@link #uniqueSet()} then increment its
      * count as reported by {@link #getCount(Object)}. Otherwise, add it to the
      * {@link #uniqueSet()} and report its count as 1.
+     * 
        
      *
      * @param object  the object to add
      * @return {@code true} always, as the size of the MultiSet is increased
@@ -112,6 +115,7 @@ interface Entry {
      * If the object is already in the {@link #uniqueSet()} then increment its
      * count as reported by {@link #getCount(Object)}. Otherwise, add it to the
      * {@link #uniqueSet()} and report its count as {@code occurrences}.
+     * 
        
      *
      * @param object  the object to add
      * @param occurrences  the number of occurrences to add, may be zero,
@@ -137,6 +141,7 @@ interface Entry {
      * 
        
      * The returned set is backed by this multiset, so any change to either
      * is immediately reflected in the other.
+     * 
        
      *
      * @return the Set of MultiSet entries
      */
@@ -147,6 +152,7 @@ interface Entry {
      * 
        
      * This MultiSet equals another object if it is also a MultiSet
      * that contains the same number of occurrences of the same elements.
+     * 
        
      *
      * @param obj  the object to compare to
      * @return true if equal
@@ -202,6 +208,7 @@ interface Entry {
      * 
        
      * If the number of occurrences to remove is greater than the actual number of
      * occurrences in the multiset, the object will be removed from the multiset.
+     * 
        
      *
      * @param object  the object to remove
      * @param occurrences  the number of occurrences to remove, may be zero,
@@ -238,6 +245,7 @@ interface Entry {
      * 
        
      * If the provided count is zero, the object will be removed from the
      * {@link #uniqueSet()}.
+     * 
        
      *
      * @param object  the object to update
      * @param count  the number of occurrences of the object
@@ -259,11 +267,13 @@ interface Entry {
      * Returns a {@link Set} of unique elements in the MultiSet.
      * 
        
      * Uniqueness constraints are the same as those in {@link java.util.Set}.
+     * 
        
      * 
        
      * The returned set is backed by this multiset, so any change to either
      * is immediately reflected in the other. Only removal operations are
      * supported, in which case all occurrences of the element are removed
      * from the backing multiset.
+     * 
        
      *
      * @return the Set of unique MultiSet elements
      */
diff --git a/src/main/java/org/apache/commons/collections4/MultiSetUtils.java b/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
index f424236e22..419574bca5 100644
--- a/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
+++ b/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
@@ -54,6 +54,7 @@ public static  MultiSet emptyMultiSet() {
      * IllegalArgumentException. It is important not to use the original multiset
      * after invoking this method, as it is a backdoor for adding invalid
      * objects.
+     * 
        
      *
      * @param  the element type
      * @param multiset the multiset to predicate, must not be null
@@ -73,7 +74,7 @@ public static  MultiSet predicatedMultiSet(final MultiSet multiset,
      * 
        
      * It is imperative that the user manually synchronize on the returned multiset
      * when iterating over it:
-     *
+     * 
        
      * 
              * MultiSet multiset = MultiSetUtils.synchronizedMultiSet(new HashMultiSet());
      * ...
diff --git a/src/main/java/org/apache/commons/collections4/MultiValuedMap.java b/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
index 5b1d6268e4..b5620e2c12 100644
--- a/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
@@ -231,8 +231,6 @@ public interface MultiValuedMap {
      */
     boolean putAll(K key, Iterable values);
 
-    // Views
-
     /**
      * Copies all mappings from the specified map to this multivalued map
      * (optional operation).
diff --git a/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java b/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
index 36f3cc48e5..14f4a9ee86 100644
--- a/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
@@ -36,13 +36,16 @@ public interface OrderedBidiMap extends BidiMap, OrderedMap {
      * 
        
      * Changes to one map will be visible in the other and vice versa.
      * This enables both directions of the map to be accessed equally.
+     * 
        
      * 
        
      * Implementations should seek to avoid creating a new object every time this
      * method is called. See {@code AbstractMap.values()} etc. Calling this
      * method on the inverse map should return the original.
+     * 
        
      * 
        
      * Implementations must return an {@code OrderedBidiMap} instance,
      * usually by forwarding to {@code inverseOrderedBidiMap()}.
+     * 
        
      *
      * @return an inverted bidirectional map
      */
diff --git a/src/main/java/org/apache/commons/collections4/OrderedMap.java b/src/main/java/org/apache/commons/collections4/OrderedMap.java
index b6f292eb7c..7707894403 100644
--- a/src/main/java/org/apache/commons/collections4/OrderedMap.java
+++ b/src/main/java/org/apache/commons/collections4/OrderedMap.java
@@ -48,6 +48,7 @@ public interface OrderedMap extends IterableMap {
      * 
        
      * An ordered map iterator is an efficient way of iterating over maps
      * in both directions.
+     * 
        
      *
      * @return a map iterator
      */
diff --git a/src/main/java/org/apache/commons/collections4/PredicateUtils.java b/src/main/java/org/apache/commons/collections4/PredicateUtils.java
index 8869fa1cb2..bced37f9ae 100644
--- a/src/main/java/org/apache/commons/collections4/PredicateUtils.java
+++ b/src/main/java/org/apache/commons/collections4/PredicateUtils.java
@@ -64,7 +64,9 @@
  * 
      • NullIsException/NullIsFalse/NullIsTrue - check for null input
  * 
      • Transformed - transforms the input before calling the predicate
  *
      + *

      * All the supplied predicates are Serializable. + *

      * * @since 3.0 */ @@ -277,6 +279,7 @@ public static Predicate invokerPredicate(final String methodName) { * For example, {@code PredicateUtils.invokerPredicate("isEmpty");} * will call the {@code isEmpty} method on the input object to * determine the predicate result. + *

      * * @param the type that the predicate queries * @param methodName the method name to call on the input object, may not be null @@ -473,7 +476,6 @@ public static Predicate orPredicate(final Predicate predicate1 return OrPredicate.orPredicate(predicate1, predicate2); } - // Transformed /** * Creates a predicate that transforms the input object before passing it * to the predicate. diff --git a/src/main/java/org/apache/commons/collections4/QueueUtils.java b/src/main/java/org/apache/commons/collections4/QueueUtils.java index aff6a24194..d5f82b55d2 100644 --- a/src/main/java/org/apache/commons/collections4/QueueUtils.java +++ b/src/main/java/org/apache/commons/collections4/QueueUtils.java @@ -55,6 +55,7 @@ public static Queue emptyQueue() { * Trying to add an invalid object results in an IllegalArgumentException. * It is important not to use the original queue after invoking this method, * as it is a backdoor for adding invalid objects. + *

      * * @param the type of the elements in the queue * @param queue the queue to predicate, must not be null @@ -73,7 +74,7 @@ public static Queue predicatedQueue(final Queue queue, final Predicate *

      * It is imperative that the user manually synchronize on the returned queue * when iterating over it: - * + *

      * 
            * Queue queue = QueueUtils.synchronizedQueue(new CircularFifoQueue());
      * ...
@@ -84,8 +85,9 @@ public static  Queue predicatedQueue(final Queue queue, final Predicate
      *     }
      * }
      *
      - * + *

      * Failure to follow this advice may result in non-deterministic behavior. + *

      * * @param the element type * @param queue the queue to synchronize, must not be null @@ -103,9 +105,11 @@ public static Queue synchronizedQueue(final Queue queue) { * Each object is passed through the transformer as it is added to the * Queue. It is important not to use the original queue after invoking this * method, as it is a backdoor for adding untransformed objects. + *

      *

      * Existing entries in the specified queue will not be transformed. * If you want that behavior, see {@link TransformedQueue#transformedQueue}. + *

      * * @param the type of the elements in the queue * @param queue the queue to predicate, must not be null diff --git a/src/main/java/org/apache/commons/collections4/SetUtils.java b/src/main/java/org/apache/commons/collections4/SetUtils.java index befd03ccd4..bdef4b5a88 100644 --- a/src/main/java/org/apache/commons/collections4/SetUtils.java +++ b/src/main/java/org/apache/commons/collections4/SetUtils.java @@ -54,6 +54,7 @@ public class SetUtils { * If the decorated sets change, this view will change as well. The contents * of this view can be transferred to another instance via the {@link #copyInto(Set)} * and {@link #toSet()} methods. + *

      * * @param the element type * @since 4.1 diff --git a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java index f338b96af9..79e60a8719 100644 --- a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java +++ b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java @@ -38,13 +38,16 @@ public interface SortedBidiMap extends OrderedBidiMap, SortedMap * Changes to one map will be visible in the other and vice versa. * This enables both directions of the map to be accessed equally. + *

      *

      * Implementations should seek to avoid creating a new object every time this * method is called. See {@code AbstractMap.values()} etc. Calling this * method on the inverse map should return the original. + *

      *

      * Implementations must return a {@code SortedBidiMap} instance, * usually by forwarding to {@code inverseSortedBidiMap()}. + *

      * * @return an inverted bidirectional map */ diff --git a/src/main/java/org/apache/commons/collections4/SplitMapUtils.java b/src/main/java/org/apache/commons/collections4/SplitMapUtils.java index bcaca1a53b..d01bea5338 100644 --- a/src/main/java/org/apache/commons/collections4/SplitMapUtils.java +++ b/src/main/java/org/apache/commons/collections4/SplitMapUtils.java @@ -217,6 +217,7 @@ public Collection values() { * If {@code get} implements {@link IterableMap} directly, no conversion will take place. * If {@code get} implements {@link Map} but not {@link IterableMap} it will be decorated. * Otherwise, an {@link Unmodifiable} {@link IterableMap} will be returned. + * * @param the key type * @param the value type * @param get to wrap, must not be null diff --git a/src/main/java/org/apache/commons/collections4/TransformerUtils.java b/src/main/java/org/apache/commons/collections4/TransformerUtils.java index 05c72c1134..7d4dfdf63c 100644 --- a/src/main/java/org/apache/commons/collections4/TransformerUtils.java +++ b/src/main/java/org/apache/commons/collections4/TransformerUtils.java @@ -357,6 +357,7 @@ public static Transformer stringValueTransformer() { * is called if the input object equals the key. If there is no match, the * default transformer is called. The default transformer is set in the map * using a null key. If no default is set, null will be returned in a default case. + *

      * * @param the input type * @param the output type @@ -394,6 +395,7 @@ public static Transformer switchMapTransformer( * null key. If no default transformer is set, null will be returned in a default * case. The ordering is that of the iterator() method on the entryset collection * of the map. + *

      * * @param the input type * @param the output type diff --git a/src/main/java/org/apache/commons/collections4/Trie.java b/src/main/java/org/apache/commons/collections4/Trie.java index 253dc53753..8791b3b44d 100644 --- a/src/main/java/org/apache/commons/collections4/Trie.java +++ b/src/main/java/org/apache/commons/collections4/Trie.java @@ -19,8 +19,7 @@ import java.util.SortedMap; /** - * Defines the interface for a prefix tree, an ordered tree data structure. For - * more information, see Tries. + * Defines the interface for a prefix tree, an ordered tree data structure. For more information, see Tries. * * @param the type of the keys in this map * @param the type of the values in this map @@ -29,19 +28,17 @@ public interface Trie extends IterableSortedMap { /** - * Returns a view of this {@link Trie} of all elements that are prefixed - * by the given key. + * Returns a view of this {@link Trie} of all elements that are prefixed by the given key. *

      - * In a {@link Trie} with fixed size keys, this is essentially a - * {@link #get(Object)} operation. + * In a {@link Trie} with fixed size keys, this is essentially a {@link #get(Object)} operation. + *

      *

      - * For example, if the {@link Trie} contains 'Anna', 'Anael', - * 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then - * a lookup of 'And' would return 'Andreas', 'Andrea', and 'Andres'. + * For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup of 'And' would return + * 'Andreas', 'Andrea', and 'Andres'. + *

      * - * @param key the key used in the search - * @return a {@link SortedMap} view of this {@link Trie} with all elements whose - * key is prefixed by the search key + * @param key the key used in the search + * @return a {@link SortedMap} view of this {@link Trie} with all elements whose key is prefixed by the search key */ SortedMap prefixMap(K key); diff --git a/src/main/java/org/apache/commons/collections4/Unmodifiable.java b/src/main/java/org/apache/commons/collections4/Unmodifiable.java index ca1acf5353..3541908d5b 100644 --- a/src/main/java/org/apache/commons/collections4/Unmodifiable.java +++ b/src/main/java/org/apache/commons/collections4/Unmodifiable.java @@ -27,9 +27,11 @@ * } * // now we know coll is modifiable * + *

      * Of course all this only works if you use the Unmodifiable classes defined * in this library. If you use the JDK unmodifiable class via {@code java.util Collections} * then the interface won't be there. + *

      * * @since 3.0 */