This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-collections.git
The following commit(s) were added to refs/heads/master by this push:
new 01655058b Javadoc
01655058b is described below
commit 01655058b0e85b85d4eabfae4be9083ec7557985
Author: Gary Gregory <[email protected]>
AuthorDate: Sun Oct 20 08:31:59 2024 -0400
Javadoc
- Close HTML tags
- Use longer lines
- Whitespace before tags
- Remove dead inline comments
= Add missing paragraph tags
---
.../apache/commons/collections4/ClosureUtils.java | 4 +++
.../commons/collections4/CollectionUtils.java | 5 +--
.../commons/collections4/EnumerationUtils.java | 1 +
.../apache/commons/collections4/FactoryUtils.java | 1 +
.../commons/collections4/FluentIterable.java | 12 +++++++
.../apache/commons/collections4/IterableGet.java | 1 +
.../apache/commons/collections4/IteratorUtils.java | 2 --
.../org/apache/commons/collections4/ListUtils.java | 40 ++++++++++++++++++----
.../apache/commons/collections4/ListValuedMap.java | 2 ++
.../apache/commons/collections4/MapIterator.java | 1 +
.../org/apache/commons/collections4/MultiMap.java | 10 ++++++
.../apache/commons/collections4/MultiMapUtils.java | 4 +++
.../org/apache/commons/collections4/MultiSet.java | 10 ++++++
.../apache/commons/collections4/MultiSetUtils.java | 3 +-
.../commons/collections4/MultiValuedMap.java | 2 --
.../commons/collections4/OrderedBidiMap.java | 3 ++
.../apache/commons/collections4/OrderedMap.java | 1 +
.../commons/collections4/PredicateUtils.java | 4 ++-
.../apache/commons/collections4/QueueUtils.java | 8 +++--
.../org/apache/commons/collections4/SetUtils.java | 1 +
.../apache/commons/collections4/SortedBidiMap.java | 3 ++
.../apache/commons/collections4/SplitMapUtils.java | 1 +
.../commons/collections4/TransformerUtils.java | 2 ++
.../java/org/apache/commons/collections4/Trie.java | 21 +++++-------
.../apache/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 def04ea9c..fe190eb86 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 class ClosureUtils {
* 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.
+ * </p>
*
* @see org.apache.commons.collections4.functors.SwitchClosure
*
@@ -275,6 +276,7 @@ public class ClosureUtils {
* 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.
+ * </p>
*
* @see org.apache.commons.collections4.functors.SwitchClosure
*
@@ -299,6 +301,7 @@ public class ClosureUtils {
* location 0 returned true. Each predicate is evaluated
* until one returns true. If no predicates evaluate to true, the default
* closure is called.
+ * </p>
*
* @see org.apache.commons.collections4.functors.SwitchClosure
*
@@ -325,6 +328,7 @@ public class ClosureUtils {
* 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.
+ * </p>
*
* @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 3aed6feae..49d7cf38a 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 class CollectionUtils {
* @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 class CollectionUtils {
*/
public static <O> List<O> collate(final Iterable<? extends O> iterableA,
final Iterable<? extends O> iterableB,
final Comparator<? super O> 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 class CollectionUtils {
return IteratorUtils.toList(iterator, totalSize);
}
final ArrayList<O> mergedList = new ArrayList<>(totalSize);
-
O lastItem = null;
while (iterator.hasNext()) {
final O item = iterator.next();
@@ -484,7 +482,6 @@ public class CollectionUtils {
}
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 7df8c409e..b6d27a36d 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 class EnumerationUtils {
* <p>
* 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.
+ * </p>
*
* @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 36d567944..06f3187f2 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 @@ import
org.apache.commons.collections4.functors.PrototypeFactory;
* <p>
* Since v4.1 only factories which are considered to be safe are
* Serializable. Factories considered to be unsafe for serialization are:
+ * </p>
* <ul>
* <li>Prototype
* <li>Instantiate
diff --git a/src/main/java/org/apache/commons/collections4/FluentIterable.java
b/src/main/java/org/apache/commons/collections4/FluentIterable.java
index c985d7e57..c58182afb 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 class FluentIterable<E> implements Iterable<E> {
* <p>
* The returned iterable's iterator supports {@code remove()} when the
* corresponding input iterator supports it.
+ * </p>
*
* @param <T> the element type
* @param iterable the iterable to wrap into a FluentIterable, may not be
null
@@ -102,6 +103,7 @@ public class FluentIterable<E> implements Iterable<E> {
* Creates a new FluentIterable of the single provided element.
* <p>
* The returned iterable's iterator does not support {@code remove()}.
+ * </p>
*
* @param <T> the element type
* @param singleton the singleton element
@@ -115,6 +117,7 @@ public class FluentIterable<E> implements Iterable<E> {
* Creates a new FluentIterable from the provided elements.
* <p>
* The returned iterable's iterator does not support {@code remove()}.
+ * </p>
*
* @param <T> the element type
* @param elements the elements to be contained in the FluentIterable
@@ -147,6 +150,7 @@ public class FluentIterable<E> implements Iterable<E> {
* provided predicate.
* <p>
* A {@code null} or empty iterable returns true.
+ * </p>
*
* @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 class FluentIterable<E> implements Iterable<E> {
* Checks if this iterable contains any element matching the provided
predicate.
* <p>
* A {@code null} or empty iterable returns false.
+ * </p>
*
* @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 class FluentIterable<E> implements Iterable<E> {
* elements of the current and provided iterable in natural order.
* <p>
* Example: natural ordering
+ * </p>
* <ul>
* <li>this contains elements [1, 3, 5, 7]
* <li>other contains elements [2, 4, 6, 8]
@@ -218,6 +224,7 @@ public class FluentIterable<E> implements Iterable<E> {
* <p>
* The returned iterable will traverse the elements in the following
* order: [1, 2, 3, 4, 5, 6, 7, 8]
+ * </p>
*
* @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 class FluentIterable<E> implements Iterable<E> {
* ordering defined by a comparator.
* <p>
* Example: descending order
+ * </p>
* <ul>
* <li>this contains elements [7, 5, 3, 1]
* <li>other contains elements [8, 6, 4, 2]
@@ -241,6 +249,7 @@ public class FluentIterable<E> implements Iterable<E> {
* <p>
* The returned iterable will traverse the elements in the following
* order: [8, 7, 6, 5, 4, 3, 2, 1]
+ * </p>
*
* @param comparator the comparator to define an ordering, may be null,
* in which case natural ordering will be used
@@ -282,10 +291,12 @@ public class FluentIterable<E> implements Iterable<E> {
* to the originating iterables and/or iterators.
* <p>
* Calling this method is equivalent to:
+ * </p>
* <pre>
* FluentIterable<E> someIterable = ...;
* FluentIterable.of(someIterable.toList());
* </pre>
+ * </p>
*
* @return a new iterable with the same contents as this iterable
*/
@@ -416,6 +427,7 @@ public class FluentIterable<E> implements Iterable<E> {
* by traversing its iterator.
* <p>
* The returned list is guaranteed to be mutable.
+ * </p>
*
* @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 39b7bcab7..4189821bf 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<K, V> extends Get<K, V> {
* <p>
* 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.
+ * </p>
* <pre>
* 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 4bf082929..1b6249204 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 class IteratorUtils {
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 class IteratorUtils {
return new NodeListIterator(Objects.requireNonNull(nodeList,
"nodeList"));
}
- // Object Graph
/**
* Gets an iterator that operates over an object graph.
* <p>
diff --git a/src/main/java/org/apache/commons/collections4/ListUtils.java
b/src/main/java/org/apache/commons/collections4/ListUtils.java
index 6a0243011..0aeb41305 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 @@ import
org.apache.commons.collections4.sequence.SequencesComparator;
* @since 1.0
*/
public class ListUtils {
+
/**
* A simple wrapper to use a CharSequence as List.
*/
@@ -178,6 +179,7 @@ public class ListUtils {
* <p>
* Shorthand for {@code list.get(0)}
* </p>
+ *
* @param <T> The list type.
* @param list The list.
* @return the first element of a list.
@@ -193,6 +195,7 @@ public class ListUtils {
* <p>
* Shorthand for {@code list.get(list.size() - 1)}
* </p>
+ *
* @param <T> The list type.
* @param list The list.
* @return the last element of a list.
@@ -210,6 +213,7 @@ public class ListUtils {
* 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.
+ * </p>
*
* @see java.util.List#hashCode()
* @param list the list to generate the hashCode for, may be null
@@ -232,6 +236,7 @@ public class ListUtils {
* <p>
* If the input List or predicate is null, or no element of the List
* matches the predicate, -1 is returned.
+ * </p>
*
* @param <E> the element type
* @param list the List to search, may be null
@@ -288,8 +293,10 @@ public class ListUtils {
* 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.
+ * </p>
* <p>
* The relevant text (slightly paraphrased as this is a static method) is:
+ * </p>
* <blockquote>
* Compares the two list objects for equality. Returns
* {@code true} if and only if both
@@ -301,9 +308,10 @@ public class ListUtils {
* definition ensures that the equals method works properly across
* different implementations of the {@code List} interface.
* </blockquote>
- *
+ * <p>
* <b>Note:</b> The behavior of this method is undefined if the lists are
* modified during the equals comparison.
+ * </p>
*
* @see java.util.List
* @param list1 the first list, may be null
@@ -339,9 +347,10 @@ public class ListUtils {
* 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.
+ * </p>
* <p>
* For instance:
- *
+ * </p>
* <pre>
* Factory<Date> factory = new Factory<Date>() {
* public Date create() {
@@ -351,11 +360,12 @@ public class ListUtils {
* List<Date> lazy = ListUtils.lazyList(new ArrayList<Date>(),
factory);
* Date date = lazy.get(3);
* </pre>
- *
+ * <p>
* 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}.
+ * </p>
*
* @param <E> the element type
* @param list the list to make lazy, must not be null
@@ -373,20 +383,22 @@ public class ListUtils {
* When the index passed to the returned list's {@link List#get(int) get}
* method is greater than the list's size, then the transformer will be
used
* to create a new object and that object will be inserted at that index.
+ * </p>
* <p>
* For instance:
- *
+ * </p>
* <pre>
* 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);
* </pre>
- *
+ * <p>
* 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}.
+ * </p>
*
* @param <E> the element type
* @param list the list to make lazy, must not be null
@@ -403,6 +415,7 @@ public class ListUtils {
* <p>
* This is a convenience method for using {@link
#longestCommonSubsequence(List, List)}
* with {@link CharSequence} instances.
+ * </p>
*
* @param charSequenceA the first sequence
* @param charSequenceB the second sequence
@@ -471,8 +484,10 @@ public class ListUtils {
* 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.
+ * </p>
* <p>
* Adapted from https://github.com/google/guava
+ * </p>
*
* @param <T> the element type
* @param list the list to return consecutive sublists of
@@ -497,6 +512,7 @@ public class ListUtils {
* 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.
+ * </p>
*
* @param <E> the element type
* @param list the list to predicate, must not be null
@@ -522,6 +538,7 @@ public class ListUtils {
* 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)}.
+ * </p>
*
* @param <E> the element type
* @param collection the collection from which items are removed (in the
returned collection)
@@ -556,6 +573,7 @@ public class ListUtils {
* 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)}.
+ * </p>
*
* @param <E> the element type
* @param collection the collection whose contents are the target of the
#retailAll operation
@@ -581,6 +599,7 @@ public class ListUtils {
* predicate into an output list.
* <p>
* A {@code null} predicate matches no elements.
+ * </p>
*
* @param <E> the element type
* @param inputCollection the collection to get the input from, may not
be null
@@ -601,6 +620,7 @@ public class ListUtils {
* predicate into an output collection.
* <p>
* If the input predicate is {@code null}, the result is an empty list.
+ * </p>
*
* @param <E> the element type
* @param inputCollection the collection to get the input from, may not be
null
@@ -625,6 +645,7 @@ public class ListUtils {
* occurrences of <Code>null</Code> and <Code>list2</Code> only
* contains one occurrence, then the returned list will still contain
* one occurrence.
+ * </p>
*
* @param <E> the element type
* @param list1 the list to subtract from
@@ -662,7 +683,7 @@ public class ListUtils {
* <p>
* You must manually synchronize on the returned list's iterator to
* avoid non-deterministic behavior:
- *
+ * </p>
* <pre>
* List list = ListUtils.synchronizedList(myList);
* synchronized (list) {
@@ -672,8 +693,9 @@ public class ListUtils {
* }
* }
* </pre>
- *
+ * <p>
* This method is just a wrapper for {@link
Collections#synchronizedList(List)}.
+ * </p>
*
* @param <E> the element type
* @param list the list to synchronize, must not be null
@@ -690,13 +712,16 @@ public class ListUtils {
* 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.
+ * </p>
* <p>
* 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.
+ * </p>
* <p>
* Existing entries in the specified list will not be transformed.
* If you want that behavior, see {@link TransformedList#transformedList}.
+ * </p>
*
* @param <E> the element type
* @param list the list to predicate, must not be null
@@ -731,6 +756,7 @@ public class ListUtils {
* Returns an unmodifiable list backed by the given list.
* <p>
* This method uses the implementation in the decorators subpackage.
+ * </p>
*
* @param <E> 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 75079bd32..37174ae5a 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<K, V> extends
MultiValuedMap<K, V> {
* {@link #containsKey(Object)} returns {@code false}. Changes to the
* returned list will update the underlying {@code ListValuedMap} and
* vice-versa.
+ * </p>
*
* @param key the key to retrieve
* @return the {@code List} of values, implementations should return an
@@ -56,6 +57,7 @@ public interface ListValuedMap<K, V> extends
MultiValuedMap<K, V> {
* The returned list <em>may</em> 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.
+ * </p>
*
* @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 54cd88e76..c9c76fc9c 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<K, V> extends Iterator<K> {
* Removes the last returned key from the underlying {@code Map} (optional
operation).
* <p>
* This method can be called once per call to {@code next()}.
+ * </p>
*
* @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 1e10fda86..ad6d4fa10 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<K, V> extends IterableMap<K,
Object> {
* <p>
* Implementations typically check all collections against all keys for
the value.
* This cannot be mandated due to backwards compatibility of this
interface.
+ * </p>
*
* @param value the value to search for
* @return true if the map contains the value
@@ -72,12 +73,15 @@ public interface MultiMap<K, V> extends IterableMap<K,
Object> {
* 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}.
+ * </p>
* <p>
* Implementations typically return {@code null} if no values have
* been mapped to the key, however the implementation may choose to
* return an empty collection.
+ * </p>
* <p>
* Implementations may choose to return a clone of the internal collection.
+ * </p>
*
* @param key the key to retrieve
* @return the {@code Collection} of values, implementations should
@@ -95,6 +99,7 @@ public interface MultiMap<K, V> extends IterableMap<K,
Object> {
* 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.
+ * </p>
*
* @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<K, V> extends IterableMap<K,
Object> {
* <p>
* Implementations typically return {@code null} from a subsequent
* {@code get(Object)}, however they may choose to return an empty
collection.
+ * </p>
*
* @param key the key to remove values from
* @return the {@code Collection} of values removed, implementations should
@@ -128,10 +134,12 @@ public interface MultiMap<K, V> extends IterableMap<K,
Object> {
* <p>
* The item is removed from the collection mapped to the specified key.
* Other values attached to that key are unaffected.
+ * </p>
* <p>
* 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.
+ * </p>
*
* @param key the key to remove from
* @param item the item to remove
@@ -148,6 +156,7 @@ public interface MultiMap<K, V> extends IterableMap<K,
Object> {
* <p>
* Implementations typically return only the count of keys in the map
* This cannot be mandated due to backwards compatibility of this
interface.
+ * </p>
*
* @return the number of key-collection mappings in this map
*/
@@ -160,6 +169,7 @@ public interface MultiMap<K, V> extends IterableMap<K,
Object> {
* Implementations typically return a collection containing the combination
* of values from all keys.
* This cannot be mandated due to backwards compatibility of this
interface.
+ * </p>
*
* @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 a91372722..77dee5afe 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 class MultiMapUtils {
* Null-safe check if the specified {@code MultiValuedMap} is empty.
* <p>
* If the provided map is null, returns true.
+ * </p>
*
* @param map the map to check, may be null
* @return true if the map is empty or null
@@ -200,13 +201,16 @@ public class MultiMapUtils {
* 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}.
+ * </p>
* <p>
* 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.
+ * </p>
* <p>
* If there are any elements already in the map being decorated, they are
* NOT transformed.
+ * </p>
*
* @param <K> the key type
* @param <V> 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 5096ad586..122a824ea 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<E> extends Collection<E> {
* <p>
* The {@link MultiSet#entrySet()} method returns a view of the multiset
whose elements
* implement this interface.
+ * </p>
*
* @param <E> the element type
*/
@@ -52,6 +53,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* More formally, two entries {@code e1} and {@code e2} represent
* the same mapping if
+ * </p>
* <pre>
* (e1.getElement()==null ? e2.getElement()==null
* :
e1.getElement().equals(e2.getElement())) &&
@@ -98,6 +100,7 @@ public interface MultiSet<E> extends Collection<E> {
* 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.
+ * </p>
*
* @param object the object to add
* @return {@code true} always, as the size of the MultiSet is increased
@@ -112,6 +115,7 @@ public interface MultiSet<E> extends Collection<E> {
* 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}.
+ * </p>
*
* @param object the object to add
* @param occurrences the number of occurrences to add, may be zero,
@@ -137,6 +141,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* The returned set is backed by this multiset, so any change to either
* is immediately reflected in the other.
+ * </p>
*
* @return the Set of MultiSet entries
*/
@@ -147,6 +152,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* This MultiSet equals another object if it is also a MultiSet
* that contains the same number of occurrences of the same elements.
+ * </p>
*
* @param obj the object to compare to
* @return true if equal
@@ -202,6 +208,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* 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.
+ * </p>
*
* @param object the object to remove
* @param occurrences the number of occurrences to remove, may be zero,
@@ -238,6 +245,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* If the provided count is zero, the object will be removed from the
* {@link #uniqueSet()}.
+ * </p>
*
* @param object the object to update
* @param count the number of occurrences of the object
@@ -259,11 +267,13 @@ public interface MultiSet<E> extends Collection<E> {
* Returns a {@link Set} of unique elements in the MultiSet.
* <p>
* Uniqueness constraints are the same as those in {@link java.util.Set}.
+ * </p>
* <p>
* 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.
+ * </p>
*
* @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 f424236e2..419574bca 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 class MultiSetUtils {
* IllegalArgumentException. It is important not to use the original
multiset
* after invoking this method, as it is a backdoor for adding invalid
* objects.
+ * </p>
*
* @param <E> the element type
* @param multiset the multiset to predicate, must not be null
@@ -73,7 +74,7 @@ public class MultiSetUtils {
* <p>
* It is imperative that the user manually synchronize on the returned
multiset
* when iterating over it:
- *
+ * </p>
* <pre>
* 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 5b1d6268e..b5620e2c1 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<K, V> {
*/
boolean putAll(K key, Iterable<? extends V> 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 36f3cc48e..14f4a9ee8 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<K, V> extends BidiMap<K,
V>, OrderedMap<K, V> {
* <p>
* Changes to one map will be visible in the other and vice versa.
* This enables both directions of the map to be accessed equally.
+ * </p>
* <p>
* 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.
+ * </p>
* <p>
* Implementations must return an {@code OrderedBidiMap} instance,
* usually by forwarding to {@code inverseOrderedBidiMap()}.
+ * </p>
*
* @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 b6f292eb7..770789440 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<K, V> extends IterableMap<K, V> {
* <p>
* An ordered map iterator is an efficient way of iterating over maps
* in both directions.
+ * </p>
*
* @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 8869fa1cb..bced37f9a 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 @@ import
org.apache.commons.collections4.functors.UniquePredicate;
* <li>NullIsException/NullIsFalse/NullIsTrue - check for null input
* <li>Transformed - transforms the input before calling the predicate
* </ul>
+ * <p>
* All the supplied predicates are Serializable.
+ * </p>
*
* @since 3.0
*/
@@ -277,6 +279,7 @@ public class PredicateUtils {
* For example, {@code PredicateUtils.invokerPredicate("isEmpty");}
* will call the {@code isEmpty} method on the input object to
* determine the predicate result.
+ * </p>
*
* @param <T> 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 class PredicateUtils {
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 aff6a2419..d5f82b55d 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 class QueueUtils {
* 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.
+ * </p>
*
* @param <E> the type of the elements in the queue
* @param queue the queue to predicate, must not be null
@@ -73,7 +74,7 @@ public class QueueUtils {
* <p>
* It is imperative that the user manually synchronize on the returned
queue
* when iterating over it:
- *
+ * </p>
* <pre>
* Queue queue = QueueUtils.synchronizedQueue(new CircularFifoQueue());
* ...
@@ -84,8 +85,9 @@ public class QueueUtils {
* }
* }
* </pre>
- *
+ * <p>
* Failure to follow this advice may result in non-deterministic behavior.
+ * </p>
*
* @param <E> the element type
* @param queue the queue to synchronize, must not be null
@@ -103,9 +105,11 @@ public class QueueUtils {
* 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.
+ * </p>
* <p>
* Existing entries in the specified queue will not be transformed.
* If you want that behavior, see {@link
TransformedQueue#transformedQueue}.
+ * </p>
*
* @param <E> 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 befd03ccd..bdef4b5a8 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.
+ * </p>
*
* @param <E> 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 f338b96af..79e60a871 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<K, V> extends
OrderedBidiMap<K, V>, SortedMap<K,
* <p>
* Changes to one map will be visible in the other and vice versa.
* This enables both directions of the map to be accessed equally.
+ * </p>
* <p>
* 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.
+ * </p>
* <p>
* Implementations must return a {@code SortedBidiMap} instance,
* usually by forwarding to {@code inverseSortedBidiMap()}.
+ * </p>
*
* @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 bcaca1a53..d01bea533 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 class SplitMapUtils {
* 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 <K> the key type
* @param <V> 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 05c72c113..7d4dfdf63 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 class TransformerUtils {
* 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.
+ * </p>
*
* @param <I> the input type
* @param <O> the output type
@@ -394,6 +395,7 @@ public class TransformerUtils {
* 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.
+ * </p>
*
* @param <I> the input type
* @param <O> 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 253dc5375..8791b3b44 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 @@ package org.apache.commons.collections4;
import java.util.SortedMap;
/**
- * Defines the interface for a prefix tree, an ordered tree data structure. For
- * more information, see <a
href="https://en.wikipedia.org/wiki/Trie";>Tries</a>.
+ * Defines the interface for a prefix tree, an ordered tree data structure.
For more information, see <a
href="https://en.wikipedia.org/wiki/Trie";>Tries</a>.
*
* @param <K> the type of the keys in this map
* @param <V> the type of the values in this map
@@ -29,19 +28,17 @@ import java.util.SortedMap;
public interface Trie<K, V> extends IterableSortedMap<K, V> {
/**
- * 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.
* <p>
- * 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.
+ * </p>
* <p>
- * 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'.
+ * </p>
*
- * @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<K, V> 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 ca1acf535..3541908d5 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 @@ package org.apache.commons.collections4;
* }
* // now we know coll is modifiable
* </pre>
+ * <p>
* 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.
+ * </p>
*
* @since 3.0
*/
