diff --git a/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java b/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java index 4f8d407c4a..528e2c861a 100644 --- a/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java +++ b/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java @@ -75,7 +75,9 @@ public PeekingIterator(final Iterator iterator) { /** * Returns the next element in iteration without advancing the underlying iterator. - * If the iterator is already exhausted, null will be returned. + *

+ * Note that if the underlying iterator is a {@link FilterIterator} or a {@link FilterListIterator}, the underlying predicate + * will not be tested if element() or {@link #peek()} has been called after the most recent invocation of {@link #next()} * * @return the next element from the iterator * @throws NoSuchElementException if the iterator is already exhausted according to {@link #hasNext()} @@ -110,6 +112,15 @@ public boolean hasNext() { return slotFilled || iterator.hasNext(); } + /** + * Returns the next element in iteration. + *

+ * Note that if the underlying iterator is a {@link FilterIterator} or a {@link FilterListIterator}, the underlying predicate + * will not be tested if {@link #element()} or {@link #peek()} has been called after the most recent invocation of next() + * + * @return the next element from the iterator + * @throws NoSuchElementException if the iterator is already exhausted according to {@link #hasNext()} + */ @Override public E next() { if (!hasNext()) { @@ -131,6 +142,9 @@ public E next() { *

* The rationale behind this is to follow the {@link java.util.Queue} interface * which uses the same terminology. + *

+ * Note that if the underlying iterator is a {@link FilterIterator} or a {@link FilterListIterator}, the underlying predicate + * will not be tested if {@link #element()} or peek() has been called after the most recent invocation of {@link #next()} * * @return the next element from the iterator */