[COLLECTIONS-856] Javadoc: Document interaction between peek and filter

iterator #515

- PR #515, plus:
- Close HTML tags
- End sentence in a period
- Use @link

src/changes/changes.xml

@@ -40,6 +40,7 @@
     <action type="fix" dev="ggregory" due-to="Gary Gregory,  Daniele" issue="COLLECTIONS-860">Javadoc CollectionBag.add* to throw ClassCastException.</action>
     <action type="fix" dev="ggregory" due-to="Gary Gregory">Fix generics in IteratorChain.IteratorChain(Collection).</action>
     <action type="fix" dev="ggregory" due-to="Gary Gregory">Fix generics in org.apache.commons.collections4.IteratorUtils.chainedIterator(Collection).</action>
+    <action type="fix" dev="ggregory" due-to="Benjamin Confino, Gary Gregory" issue="COLLECTIONS-856">Javadoc: Document interaction between peek and filter iterator #515.</action>
     <!-- ADD -->
     <action type="add" dev="ggregory" due-to="Gary Gregory">LayerManager.Builder implements Supplier.</action>
     <action type="add" dev="ggregory" due-to="Gary Gregory, hemanth0525">Add CollectionUtils.duplicateList(Collection).</action>

src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java

@@ -23,8 +23,7 @@
 /**
  * Decorates an iterator to support one-element lookahead while iterating.
  * <p>
- * The decorator supports the removal operation, but an {@link IllegalStateException}
- * will be thrown if {@link #remove()} is called directly after a call to
+ * The decorator supports the removal operation, but an {@link IllegalStateException} will be thrown if {@link #remove()} is called directly after a call to
  * {@link #peek()} or {@link #element()}.
  * </p>
  *
@@ -39,8 +38,8 @@ public class PeekingIterator<E> implements Iterator<E> {
      * If the iterator is already a {@link PeekingIterator} it is returned directly.
      * </p>
      *
-     * @param <E>  the element type
-     * @param iterator  the iterator to decorate
+     * @param <E>      the element type
+     * @param iterator the iterator to decorate
      * @return a new peeking iterator
      * @throws NullPointerException if the iterator is null
      */
@@ -69,15 +68,18 @@ public static <E> PeekingIterator<E> peekingIterator(final Iterator<? extends E>
     /**
      * Constructs a new instance.
      *
-     * @param iterator  the iterator to decorate
+     * @param iterator the iterator to decorate
      */
     public PeekingIterator(final Iterator<? extends E> iterator) {
         this.iterator = iterator;
     }
 
     /**
-     * Returns the next element in iteration without advancing the underlying iterator.
-     * If the iterator is already exhausted, null will be returned.
+     * Returns the next element in iteration without advancing the underlying iterator. If the iterator is already exhausted, null will be returned.
+     * <p>
+     * Note that if the underlying iterator is a {@link FilterIterator} or a {@link FilterListIterator}, the underlying predicate will <em>not</em> be tested if
+     * element() or {@link #peek()} has been called after the most recent invocation of {@link #next()}
+     * </p>
      *
      * @return the next element from the iterator
      * @throws NoSuchElementException if the iterator is already exhausted according to {@link #hasNext()}
@@ -112,6 +114,16 @@ public boolean hasNext() {
         return slotFilled || iterator.hasNext();
     }
 
+    /**
+     * Returns the next element in iteration.
+     * <p>
+     * Note that if the underlying iterator is a {@link FilterIterator} or a {@link FilterListIterator}, the underlying predicate will <em>not</em> be tested if
+     * {@link #element()} or {@link #peek()} has been called after the most recent invocation of {@link #next()}.
+     * </p>
+     *
+     * @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()) {
@@ -125,15 +137,17 @@ public E next() {
     }
 
     /**
-     * Returns the next element in iteration without advancing the underlying iterator.
-     * If the iterator is already exhausted, null will be returned.
+     * Returns the next element in iteration without advancing the underlying iterator. If the iterator is already exhausted, null will be returned.
+     * <p>
+     * Note: this method does not throw a {@link NoSuchElementException} if the iterator is already exhausted. If you want such a behavior, use
+     * {@link #element()} instead.
+     * </p>
      * <p>
-     * Note: this method does not throw a {@link NoSuchElementException} if the iterator
-     * is already exhausted. If you want such a behavior, use {@link #element()} instead.
+     * The rationale behind this is to follow the {@link java.util.Queue} interface which uses the same terminology.
      * </p>
      * <p>
-     * 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 <em>not</em> be tested if
+     * {@link #element()} or peek() has been called after the most recent invocation of {@link #next()}.
      * </p>
      *
      * @return the next element from the iterator
@@ -146,8 +160,7 @@ public E peek() {
     /**
      * {@inheritDoc}
      *
-     * @throws IllegalStateException if {@link #peek()} or {@link #element()} has been called
-     *   prior to the call to {@link #remove()}
+     * @throws IllegalStateException if {@link #peek()} or {@link #element()} has been called prior to the call to {@link #remove()}.
      */
     @Override
     public void remove() {