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 b8ff7e3e2 Javadoc
b8ff7e3e2 is described below
commit b8ff7e3e267dad214f9db9259d0fa12f78949b24
Author: Gary Gregory <[email protected]>
AuthorDate: Sat Oct 19 14:50:49 2024 -0400
Javadoc
- Close HTML tags
- Remove dead inline comments
---
.../apache/commons/collections4/IteratorUtils.java | 66 ++++++++++++++++------
1 file changed, 48 insertions(+), 18 deletions(-)
diff --git a/src/main/java/org/apache/commons/collections4/IteratorUtils.java
b/src/main/java/org/apache/commons/collections4/IteratorUtils.java
index f8678be60..4bf082929 100644
--- a/src/main/java/org/apache/commons/collections4/IteratorUtils.java
+++ b/src/main/java/org/apache/commons/collections4/IteratorUtils.java
@@ -112,7 +112,6 @@ public class IteratorUtils {
*/
private static final String DEFAULT_TOSTRING_DELIMITER = ", ";
- // Arrays
/**
* Gets an iterator over an object array.
*
@@ -161,6 +160,7 @@ public class IteratorUtils {
* <p>
* This method will handle primitive arrays as well as object arrays.
* The primitives will be wrapped in the appropriate wrapper class.
+ * </p>
*
* @param <E> the element type
* @param array the array over which to iterate
@@ -177,6 +177,7 @@ public class IteratorUtils {
* <p>
* This method will handle primitive arrays as well as object arrays.
* The primitives will be wrapped in the appropriate wrapper class.
+ * </p>
*
* @param <E> the element type
* @param array the array over which to iterate
@@ -196,6 +197,7 @@ public class IteratorUtils {
* <p>
* This method will handle primitive arrays as well as object arrays.
* The primitives will be wrapped in the appropriate wrapper class.
+ * </p>
*
* @param <E> the element type
* @param array the array over which to iterate
@@ -257,6 +259,7 @@ public class IteratorUtils {
* <p>
* This method will handle primitive arrays as well as object arrays.
* The primitives will be wrapped in the appropriate wrapper class.
+ * </p>
*
* @param <E> the element type
* @param array the array over which to iterate
@@ -273,6 +276,7 @@ public class IteratorUtils {
* <p>
* This method will handle primitive arrays as well as object arrays.
* The primitives will be wrapped in the appropriate wrapper class.
+ * </p>
*
* @param <E> the element type
* @param array the array over which to iterate
@@ -291,6 +295,7 @@ public class IteratorUtils {
* <p>
* This method will handle primitive arrays as well as object arrays.
* The primitives will be wrapped in the appropriate wrapper class.
+ * </p>
*
* @param <E> the element type
* @param array the array over which to iterate
@@ -331,7 +336,6 @@ public class IteratorUtils {
return new IteratorIterable<>(iterator, false);
}
- // Views
/**
* Gets an iterator that provides an iterator view of the given
enumeration.
*
@@ -398,6 +402,7 @@ public class IteratorUtils {
* <p>
* The iterator is immediately advanced until it reaches the position at
* {@code offset}, incurring O(n) time.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to decorate
@@ -485,8 +490,10 @@ public class IteratorUtils {
* Given two ordered {@link Iterator}s {@code A} and {@code B},
* the {@link Iterator#next()} method will return the lesser of
* {@code A.next()} and {@code B.next()} and so on.
+ * </p>
* <p>
* The comparator is optional. If null is specified then natural order is
used.
+ * </p>
*
* @param <E> the element type
* @param comparator the comparator to use, may be null for natural order
@@ -510,8 +517,10 @@ public class IteratorUtils {
* Given two ordered {@link Iterator}s {@code A} and {@code B},
* the {@link Iterator#next()} method will return the lesser of
* {@code A.next()} and {@code B.next()} and so on.
+ * </p>
* <p>
* The comparator is optional. If null is specified then natural order is
used.
+ * </p>
*
* @param <E> the element type
* @param comparator the comparator to use, may be null for natural order
@@ -535,8 +544,10 @@ public class IteratorUtils {
* Given two ordered {@link Iterator}s {@code A} and {@code B},
* the {@link Iterator#next()} method will return the lesser of
* {@code A.next()} and {@code B.next()}.
+ * </p>
* <p>
* The comparator is optional. If null is specified then natural order is
used.
+ * </p>
*
* @param <E> the element type
* @param comparator the comparator to use, may be null for natural order
@@ -554,12 +565,11 @@ public class IteratorUtils {
return new CollatingIterator<>(comp, iterator1, iterator2);
}
- // Chained
-
/**
* Checks if the object is contained in the given iterator.
* <p>
* A {@code null} or empty iterator returns false.
+ * </p>
*
* @param <E> the type of object the {@link Iterator} contains
* @param iterator the iterator to check, may be null
@@ -571,11 +581,11 @@ public class IteratorUtils {
return matchesAny(iterator, EqualPredicate.equalPredicate(object));
}
- // Empty
/**
* Gets an empty iterator.
* <p>
* This iterator is a valid iterator object that will iterate over nothing.
+ * </p>
*
* @param <E> the element type
* @return an iterator over nothing
@@ -589,6 +599,7 @@ public class IteratorUtils {
* <p>
* This iterator is a valid list iterator object that will iterate
* over nothing.
+ * </p>
*
* @param <E> the element type
* @return a list iterator over nothing
@@ -602,6 +613,7 @@ public class IteratorUtils {
* <p>
* This iterator is a valid map iterator object that will iterate
* over nothing.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -616,6 +628,7 @@ public class IteratorUtils {
* <p>
* This iterator is a valid iterator object that will iterate
* over nothing.
+ * </p>
*
* @param <E> the element type
* @return an ordered iterator over nothing
@@ -629,6 +642,7 @@ public class IteratorUtils {
* <p>
* This iterator is a valid map iterator object that will iterate
* over nothing.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -638,12 +652,12 @@ public class IteratorUtils {
return EmptyOrderedMapIterator.<K, V>emptyOrderedMapIterator();
}
- // Filtered
/**
* Gets an iterator that filters another iterator.
* <p>
* The returned iterator will only return objects that match the specified
* filtering predicate.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to use, not null
@@ -663,6 +677,7 @@ public class IteratorUtils {
* <p>
* The returned iterator will only return objects that match the specified
* filtering predicate.
+ * </p>
*
* @param <E> the element type
* @param listIterator the list iterator to use, not null
@@ -763,6 +778,7 @@ public class IteratorUtils {
* Executes the given closure on each but the last element in the iterator.
* <p>
* If the input iterator is null no change is made.
+ * </p>
*
* @param <E> the type of object the {@link Iterator} contains
* @param iterator the iterator to get the input from, may be null
@@ -835,6 +851,7 @@ public class IteratorUtils {
* Gets a suitable Iterator for the given object.
* <p>
* This method can handle objects as follows
+ * </p>
* <ul>
* <li>null - empty iterator
* <li>Iterator - returned directly
@@ -897,13 +914,12 @@ public class IteratorUtils {
return singletonIterator(obj);
}
- // Peeking
-
/**
* Returns the index of the first element in the specified iterator that
* matches the given predicate.
* <p>
* A {@code null} or empty iterator returns -1.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to search, may be null
@@ -926,12 +942,11 @@ public class IteratorUtils {
return CollectionUtils.INDEX_NOT_FOUND;
}
- // Pushback
-
/**
* Checks if the given iterator is empty.
* <p>
* A {@code null} or empty iterator returns true.
+ * </p>
*
* @param iterator the {@link Iterator} to use, may be null
* @return true if the iterator is exhausted or null, false otherwise
@@ -941,13 +956,13 @@ public class IteratorUtils {
return iterator == null || !iterator.hasNext();
}
- // Looping
/**
* Gets an iterator that loops continuously over the supplied collection.
* <p>
* The iterator will only stop looping if the remove method is called
* enough times to empty the collection, or if the collection is empty
* to start with.
+ * </p>
*
* @param <E> the element type
* @param collection the collection to iterate over, not null
@@ -963,6 +978,7 @@ public class IteratorUtils {
* <p>
* The iterator will only stop looping if the remove method is called
* enough times to empty the list, or if the list is empty to start with.
+ * </p>
*
* @param <E> the element type
* @param list the list to iterate over, not null
@@ -978,6 +994,7 @@ public class IteratorUtils {
* Answers true if a predicate is true for every element of an iterator.
* <p>
* A {@code null} or empty iterator returns true.
+ * </p>
*
* @param <E> the type of object the {@link Iterator} contains
* @param iterator the {@link Iterator} to use, may be null
@@ -1005,6 +1022,7 @@ public class IteratorUtils {
* Answers true if a predicate is true for any element of the iterator.
* <p>
* A {@code null} or empty iterator returns false.
+ * </p>
*
* @param <E> the type of object the {@link Iterator} contains
* @param iterator the {@link Iterator} to use, may be null
@@ -1022,6 +1040,7 @@ public class IteratorUtils {
* The returned {@link Iterator} can be used for a single iteration.
* <p>
* Convenience method, allows easy iteration over NodeLists:
+ * </p>
* <pre>
* Iterator<Node> iterator = IteratorUtils.nodeListIterator(node);
* for (Node childNode : IteratorUtils.asIterable(iterator)) {
@@ -1038,7 +1057,6 @@ public class IteratorUtils {
return new NodeListIterator(Objects.requireNonNull(node, "node"));
}
- // org.w3c.dom.NodeList iterators
/**
* Gets an {@link Iterator} that wraps the specified {@link NodeList}.
* The returned {@link Iterator} can be used for a single iteration.
@@ -1060,8 +1078,10 @@ public class IteratorUtils {
* The iteration starts from a single root object.
* It uses a {@code Transformer} to extract the iterators and elements.
* Its main benefit is that no intermediate {@code List} is created.
+ * </p>
* <p>
* For example, consider an object graph:
+ * </p>
* <pre>
* |- Branch -- Leaf
* | \- Leaf
@@ -1073,8 +1093,10 @@ public class IteratorUtils {
* |- Tree | /- Leaf
* |- Branch -- Leaf
* |- Branch -- Leaf</pre>
+ * <p>
* The following {@code Transformer}, used in this class, will extract all
* the Leaf objects without creating a combined intermediate list:
+ * </p>
* <pre>
* public Object transform(Object input) {
* if (input instanceof Forest) {
@@ -1097,9 +1119,11 @@ public class IteratorUtils {
* either an iterator or an object. If the object is an Iterator, the next
element
* from that iterator is obtained and the process repeats. If the element
is an object
* it is returned.
+ * </p>
* <p>
* Under many circumstances, linking Iterators together in this manner is
* more efficient (and convenient) than using nested for loops to extract
a list.
+ * </p>
*
* @param <E> the element type
* @param root the root object to start iterating from, null results in
an empty iterator
@@ -1138,12 +1162,12 @@ public class IteratorUtils {
return PushbackIterator.pushbackIterator(iterator);
}
- // Singleton
/**
* Gets a singleton iterator.
* <p>
* This iterator is a valid iterator object that will iterate over
* the specified object.
+ * </p>
*
* @param <E> the element type
* @param object the single object over which to iterate
@@ -1158,6 +1182,7 @@ public class IteratorUtils {
* <p>
* This iterator is a valid list iterator object that will iterate over
* the specified object.
+ * </p>
*
* @param <E> the element type
* @param object the single object over which to iterate
@@ -1171,6 +1196,7 @@ public class IteratorUtils {
* Returns the number of elements contained in the given iterator.
* <p>
* A {@code null} or empty iterator returns {@code 0}.
+ * </p>
*
* @param iterator the iterator to check, may be null
* @return the number of elements contained in the iterator
@@ -1187,7 +1213,6 @@ public class IteratorUtils {
return size;
}
- // Skipping
/**
* Decorates the specified iterator to skip the first N elements.
*
@@ -1208,6 +1233,7 @@ public class IteratorUtils {
* <p>
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, this is converted to an array.
+ * </p>
*
* @param iterator the iterator to use, not null
* @return an array of the iterator contents
@@ -1224,6 +1250,7 @@ public class IteratorUtils {
* <p>
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, this is converted to an array.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to use, not null
@@ -1241,13 +1268,12 @@ public class IteratorUtils {
return list.toArray(array);
}
- // Utility methods
-
/**
* Gets a list based on an iterator.
* <p>
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, the list is returned.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to use, not null
@@ -1263,6 +1289,7 @@ public class IteratorUtils {
* <p>
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, the list is returned.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to use, not null
@@ -1288,6 +1315,7 @@ public class IteratorUtils {
* <p>
* As the wrapped Iterator is traversed, a LinkedList of its values is
* cached, permitting all required operations of ListIterator.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to use, may not be null
@@ -1306,6 +1334,7 @@ public class IteratorUtils {
* enclosed in square brackets ({@code "[]"}). Adjacent elements are
separated
* by the characters {@code ", "} (a comma followed by a space). Elements
are
* converted to strings as by {@code String.valueOf(Object)}.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to convert to a string, may be null
@@ -1325,6 +1354,7 @@ public class IteratorUtils {
* enclosed in square brackets ({@code "[]"}). Adjacent elements are
separated
* by the characters {@code ", "} (a comma followed by a space). Elements
are
* converted to strings as by using the provided {@code transformer}.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to convert to a string, may be null
@@ -1346,6 +1376,7 @@ public class IteratorUtils {
* enclosed by the provided {@code prefix} and {@code suffix}. Adjacent
elements
* are separated by the provided {@code delimiter}. Elements are converted
to
* strings as by using the provided {@code transformer}.
+ * </p>
*
* @param <E> the element type
* @param iterator the iterator to convert to a string, may be null
@@ -1381,12 +1412,12 @@ public class IteratorUtils {
return stringBuilder.toString();
}
- // Transformed
/**
* Gets an iterator that transforms the elements of another iterator.
* <p>
* The transformation occurs during the next() method and the underlying
* iterator is unaffected by the transformation.
+ * </p>
*
* @param <I> the input type
* @param <O> the output type
@@ -1403,7 +1434,6 @@ public class IteratorUtils {
return new TransformIterator<>(iterator, transformer);
}
- // Unmodifiable
/**
* Gets an immutable version of an {@link Iterator}. The returned object
* will always throw an {@link UnsupportedOperationException} for
