Merge branch 'pr-165'

This closes #165
apache · Aug 26, 2020 · a60636f · a60636f
2 parents 0fbfbfc + aa2a29f
commit a60636f
Show file tree

Hide file tree

Showing 36 changed files with 102 additions and 103 deletions.
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -21,6 +21,9 @@
   </properties>
   <body>
   <release version="4.5" date="2020-MM-DD" description="Maintenance release.">
+    <action issue="COLLECTIONS-764" dev="kinow" type="fix" due-to="XenoAmess">
+      Refine javadoc and fix typos.
+    </action>
     <action issue="COLLECTIONS-765" dev="kinow" type="fix" due-to="Tobias Kiecker">
       Update Javadoc of ListIteratorWrapper#remove.
     </action>

diff --git a/src/main/java/org/apache/commons/collections4/Bag.java b/src/main/java/org/apache/commons/collections4/Bag.java
@@ -233,7 +233,7 @@ public interface Bag<E> extends Collection<E> {
 //     * Gets a hash code for the Bag compatible with the definition of equals.
 //     * The hash code is defined as the sum total of a hash code for each element.
 //     * The per element hash code is defined as
-//     * {@code (e==null ? 0 : e.hashCode()) ^ noOccurances)}.
+//     * {@code (e==null ? 0 : e.hashCode()) ^ noOccurrences)}.
 //     * This hash code definition is compatible with the Set interface.
 //     *
 //     * @return the hash code of the Bag

diff --git a/src/main/java/org/apache/commons/collections4/MultiSet.java b/src/main/java/org/apache/commons/collections4/MultiSet.java
@@ -204,7 +204,7 @@ public interface MultiSet<E> extends Collection<E> {
      * Gets a hash code for the MultiSet compatible with the definition of equals.
      * The hash code is defined as the sum total of a hash code for each element.
      * The per element hash code is defined as
-     * {@code (e==null ? 0 : e.hashCode()) ^ noOccurances)}.
+     * {@code (e==null ? 0 : e.hashCode()) ^ noOccurrences)}.
      *
      * @return the hash code of the MultiSet
      */
@@ -260,7 +260,7 @@ interface Entry<E> {
          * <p>
          * The hash code of a multiset entry {@code e} is defined to be:
          * <pre>
-         *      (e==null ? 0 : e.hashCode()) ^ noOccurances)
+         *      (e==null ? 0 : e.hashCode()) ^ noOccurrences)
          * </pre>
          *
          * @return the hash code value for this multiset entry

diff --git a/src/main/java/org/apache/commons/collections4/Predicate.java b/src/main/java/org/apache/commons/collections4/Predicate.java
@@ -27,7 +27,7 @@
  * <p>
  * Standard implementations of common predicates are provided by
  * {@link PredicateUtils}. These include true, false, instanceof, equals, and,
- * or, not, method invokation and null testing.
+ * or, not, method invocation and null testing.
  * </p>
  *
  * @param <T> the type that the predicate queries

diff --git a/src/main/java/org/apache/commons/collections4/bag/AbstractMapBag.java b/src/main/java/org/apache/commons/collections4/bag/AbstractMapBag.java
@@ -579,7 +579,7 @@ public boolean equals(final Object object) {
      * Gets a hash code for the Bag compatible with the definition of equals.
      * The hash code is defined as the sum total of a hash code for each
      * element. The per element hash code is defined as
-     * {@code (e==null ? 0 : e.hashCode()) ^ noOccurances)}. This hash code
+     * {@code (e==null ? 0 : e.hashCode()) ^ noOccurrences)}. This hash code
      * is compatible with the Set interface.
      *
      * @return the hash code of the Bag

diff --git a/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java b/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
@@ -85,7 +85,7 @@ private void writeObject(final ObjectOutputStream out) throws IOException {
      * @param in  the input stream
      * @throws IOException if an error occurs while reading from the stream
      * @throws ClassNotFoundException if an object read from the stream can not be loaded
-     * @throws ClassCastException if deserialised object has wrong type
+     * @throws ClassCastException if deserialized object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

diff --git a/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java b/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
@@ -76,7 +76,7 @@ private void writeObject(final ObjectOutputStream out) throws IOException {
      * @param in  the input stream
      * @throws IOException if an error occurs while reading from the stream
      * @throws ClassNotFoundException if an object read from the stream can not be loaded
-     * @throws ClassCastException if deserialised object has wrong type
+     * @throws ClassCastException if deserialized object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

diff --git a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
@@ -97,7 +97,7 @@ private void writeObject(final ObjectOutputStream out) throws IOException {
      * @param in  the input stream
      * @throws IOException if an error occurs while reading from the stream
      * @throws ClassNotFoundException if an object read from the stream can not be loaded
-     * @throws ClassCastException if deserialised object has wrong type
+     * @throws ClassCastException if deserialized object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

diff --git a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
@@ -94,7 +94,7 @@ private void writeObject(final ObjectOutputStream out) throws IOException {
      * @param in  the input stream
      * @throws IOException if an error occurs while reading from the stream
      * @throws ClassNotFoundException if an object read from the stream can not be loaded
-     * @throws ClassCastException if deserialised object has wrong type
+     * @throws ClassCastException if deserialized object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

diff --git a/src/main/java/org/apache/commons/collections4/iterators/CollatingIterator.java b/src/main/java/org/apache/commons/collections4/iterators/CollatingIterator.java
@@ -194,7 +194,7 @@ public List<Iterator<? extends E>> getIterators() {
     }
 
     /**
-     * Gets the {@link Comparator} by which collatation occurs.
+     * Gets the {@link Comparator} by which collation occurs.
      *
      * @return the {@link Comparator}
      */
@@ -383,8 +383,8 @@ private boolean anyValueSet(final BitSet set) {
      * Returns {@code true} iff any {@link Iterator} in the given list has
      * a next value.
      */
-    private boolean anyHasNext(final List<Iterator<? extends E>> iters) {
-        for (final Iterator<? extends E> iterator : iters) {
+    private boolean anyHasNext(final List<Iterator<? extends E>> iterators) {
+        for (final Iterator<? extends E> iterator : iterators) {
             if (iterator.hasNext()) {
                 return true;
             }

diff --git a/src/main/java/org/apache/commons/collections4/iterators/ObjectGraphIterator.java b/src/main/java/org/apache/commons/collections4/iterators/ObjectGraphIterator.java
@@ -191,7 +191,7 @@ protected void findNextByIterator(final Iterator<? extends E> iterator) {
             }
             findNext(next);
         }
-        // if we havn't found the next value and iterators are not yet exhausted
+        // if we haven't found the next value and iterators are not yet exhausted
         if (!hasNext && !stack.isEmpty()) {
             // current iterator exhausted, go up a level
             currentIterator = stack.pop();

diff --git a/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java b/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
@@ -312,7 +312,7 @@ public void putAll(final Map<? extends K, ? extends V> map) {
      * uses {@link #put(Object, Object)}.
      * <p>
      * It is private to allow the constructor to still call it
-     * even when putAll is overriden.
+     * even when putAll is overridden.
      *
      * @param map  the map to add
      * @throws NullPointerException if the map is null

diff --git a/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java b/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
@@ -766,7 +766,7 @@ protected ReferenceEntry<K, V> next() {
         }
 
         /**
-         * This method can be overriden to provide custom logic to purge value
+         * This method can be overridden to provide custom logic to purge value
          */
         protected void nullValue() {
             value = null;

diff --git a/src/main/java/org/apache/commons/collections4/map/LRUMap.java b/src/main/java/org/apache/commons/collections4/map/LRUMap.java
@@ -110,7 +110,7 @@ public LRUMap(final int maxSize, final int initialSize) {
      * Constructs a new, empty map with the specified maximum size.
      *
      * @param maxSize  the maximum size of the map
-     * @param scanUntilRemovable  scan until a removeable entry is found, default false
+     * @param scanUntilRemovable  scan until a removable entry is found, default false
      * @throws IllegalArgumentException if the maximum size is less than one
      * @since 3.1
      */
@@ -152,7 +152,7 @@ public LRUMap(final int maxSize, final int initialSize, final float loadFactor)
      *
      * @param maxSize  the maximum size of the map
      * @param loadFactor  the load factor
-     * @param scanUntilRemovable  scan until a removeable entry is found, default false
+     * @param scanUntilRemovable  scan until a removable entry is found, default false
      * @throws IllegalArgumentException if the maximum size is less than one
      * @throws IllegalArgumentException if the load factor is less than zero
      * @since 3.1
@@ -167,7 +167,7 @@ public LRUMap(final int maxSize, final float loadFactor, final boolean scanUntil
      * @param maxSize  the maximum size of the map
      * @param initialSize  the initial size of the map
      * @param loadFactor  the load factor
-     * @param scanUntilRemovable  scan until a removeable entry is found, default false
+     * @param scanUntilRemovable  scan until a removable entry is found, default false
      * @throws IllegalArgumentException if the maximum size is less than one
      * @throws IllegalArgumentException if the initial size is negative or larger than the maximum size
      * @throws IllegalArgumentException if the load factor is less than zero
@@ -183,7 +183,7 @@ public LRUMap(final int maxSize,
             throw new IllegalArgumentException("LRUMap max size must be greater than 0");
         }
         if (initialSize > maxSize) {
-            throw new IllegalArgumentException("LRUMap initial size must not be greather than max size");
+            throw new IllegalArgumentException("LRUMap initial size must not be greater than max size");
         }
         this.maxSize = maxSize;
         this.scanUntilRemovable = scanUntilRemovable;
@@ -208,7 +208,7 @@ public LRUMap(final Map<? extends K, ? extends V> map) {
      * <p>The maximum size is set from the map's size.</p>
      *
      * @param map  the map to copy
-     * @param scanUntilRemovable  scan until a removeable entry is found, default false
+     * @param scanUntilRemovable  scan until a removable entry is found, default false
      * @throws NullPointerException if the map is null
      * @throws IllegalArgumentException if the map is empty
      * @since 3.1

diff --git a/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java b/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
@@ -93,7 +93,7 @@ private void writeObject(final ObjectOutputStream out) throws IOException {
      * @param in  the input stream
      * @throws IOException if an error occurs while reading from the stream
      * @throws ClassNotFoundException if an object read from the stream can not be loaded
-     * @throws ClassCastException if deserialised object has wrong type
+     * @throws ClassCastException if deserialized object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {

diff --git a/src/main/java/org/apache/commons/collections4/queue/CircularFifoQueue.java b/src/main/java/org/apache/commons/collections4/queue/CircularFifoQueue.java
@@ -39,7 +39,7 @@
  * were added.  The iteration order is the same as the removal order.
  * </p>
  * <p>
- * The {@link #add(Object)}, {@link #remove()}, {@link #peek()}, {@link #poll},
+ * The {@link #add(Object)}, {@link #remove()}, {@link #peek()}, {@link #poll()},
  * {@link #offer(Object)} operations all perform in constant time.
  * All other operations perform in linear time or worse.
  * </p>

diff --git a/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java b/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java
@@ -71,8 +71,8 @@ protected AbstractPatriciaTrie(final KeyAnalyzer<? super K> keyAnalyzer) {
     }
 
     /**
-     * Constructs a new {@link org.apache.commons.collections4.Trie org.apache.commons.collections4.Trie Trie}
-     * using the given {@link KeyAnalyzer} and initializes the {@link org.apache.commons.collections4.Trie Trie}
+     * Constructs a new {@link org.apache.commons.collections4.Trie}
+     * using the given {@link KeyAnalyzer} and initializes the {@link org.apache.commons.collections4.Trie}
      * with the values from the provided {@link Map}.
      */
     protected AbstractPatriciaTrie(final KeyAnalyzer<? super K> keyAnalyzer,
@@ -103,15 +103,15 @@ public int size() {
     }
 
     /**
-     * A helper method to increment the {@link Trie} size and the modification counter.
+     * A helper method to increment the {@link org.apache.commons.collections4.Trie} size and the modification counter.
      */
     void incrementSize() {
         size++;
         incrementModCount();
     }
 
     /**
-     * A helper method to decrement the {@link Trie} size and increment the modification counter.
+     * A helper method to decrement the {@link org.apache.commons.collections4.Trie} size and increment the modification counter.
      */
     void decrementSize() {
         size--;
@@ -187,7 +187,7 @@ public V put(final K key, final V value) {
     }
 
     /**
-     * Adds the given {@link TrieEntry} to the {@link Trie}.
+     * Adds the given {@link TrieEntry} to the {@link org.apache.commons.collections4.Trie}.
      */
     TrieEntry<K, V> addEntry(final TrieEntry<K, V> entry, final int lengthInBits) {
         TrieEntry<K, V> current = root.left;
@@ -341,10 +341,6 @@ public V selectValue(final K key) {
         return entry.getValue();
     }
 
-    /**
-     * This is equivalent to the other {@link #selectR(TrieEntry, int, Object, int, Cursor, Reference)}
-     * method but without its overhead because we're selecting only one best matching Entry from the {@link Trie}.
-     */
     private boolean selectR(final TrieEntry<K, V> h, final int bitIndex,
                             final K key, final int lengthInBits,
                             final Reference<Map.Entry<K, V>> reference) {
@@ -468,7 +464,7 @@ TrieEntry<K, V> getNearestEntryForKey(final K key, final int lengthInBits) {
     }
 
     /**
-     * Removes a single entry from the {@link Trie}.
+     * Removes a single entry from the {@link org.apache.commons.collections4.Trie}.
      *
      * If we found a Key (Entry h) then figure out if it's
      * an internal (hard to remove) or external Entry (easy
@@ -488,7 +484,7 @@ V removeEntry(final TrieEntry<K, V> h) {
     }
 
     /**
-     * Removes an external entry from the {@link Trie}.
+     * Removes an external entry from the {@link org.apache.commons.collections4.Trie}.
      *
      * If it's an external Entry then just remove it.
      * This is very easy and straight forward.
@@ -519,7 +515,7 @@ private void removeExternalEntry(final TrieEntry<K, V> h) {
     }
 
     /**
-     * Removes an internal entry from the {@link Trie}.
+     * Removes an internal entry from the {@link org.apache.commons.collections4.Trie}.
      *
      * If it's an internal Entry then "good luck" with understanding
      * this code. The Idea is essentially that Entry p takes Entry h's
@@ -734,7 +730,7 @@ && isValidUplink(current.parent.right, current.parent)) {
     }
 
     /**
-     * Returns the first entry the {@link Trie} is storing.
+     * Returns the first entry the {@link org.apache.commons.collections4.Trie} is storing.
      * <p>
      * This is implemented by going always to the left until
      * we encounter a valid uplink. That uplink is the first key.
@@ -824,14 +820,14 @@ public SortedMap<K, V> prefixMap(final K key) {
     }
 
     /**
-     * Returns a view of this {@link Trie} of all elements that are prefixed
+     * Returns a view of this {@link org.apache.commons.collections4.Trie} of all elements that are prefixed
      * by the number of bits in the given Key.
      * <p>
      * The view that this returns is optimized to have a very efficient
      * {@link Iterator}. The {@link SortedMap#firstKey()},
      * {@link SortedMap#lastKey()} &amp; {@link Map#size()} methods must
      * iterate over all possible values in order to determine the results.
-     * This information is cached until the PATRICIA {@link Trie} changes.
+     * This information is cached until the PATRICIA {@link org.apache.commons.collections4.Trie} changes.
      * All other methods (except {@link Iterator}) must compare the given
      * key to the prefix to ensure that it is within the range of the view.
      * The {@link Iterator}'s remove method must also relocate the subtree
@@ -841,7 +837,7 @@ public SortedMap<K, V> prefixMap(final K key) {
      * @param key  the key to use in the search
      * @param offsetInBits  the prefix offset
      * @param lengthInBits  the number of significant prefix bits
-     * @return a {@link SortedMap} view of this {@link Trie} with all elements whose
+     * @return a {@link SortedMap} view of this {@link org.apache.commons.collections4.Trie} with all elements whose
      *   key is prefixed by the search key
      */
     private SortedMap<K, V> getPrefixMapByBits(final K key, final int offsetInBits, final int lengthInBits) {
@@ -1141,7 +1137,7 @@ TrieEntry<K, V> subtree(final K prefix, final int offsetInBits, final int length
     }
 
     /**
-     * Returns the last entry the {@link Trie} is storing.
+     * Returns the last entry the {@link org.apache.commons.collections4.Trie} is storing.
      *
      * <p>This is implemented by going always to the right until
      * we encounter a valid uplink. That uplink is the last key.
@@ -1380,7 +1376,7 @@ public String toString() {
 
 
     /**
-     * This is a entry set view of the {@link Trie} as returned by {@link Map#entrySet()}.
+     * This is a entry set view of the {@link org.apache.commons.collections4.Trie} as returned by {@link Map#entrySet()}.
      */
     private class EntrySet extends AbstractSet<Map.Entry<K, V>> {
 
@@ -1434,7 +1430,7 @@ public Map.Entry<K, V> next() {
     }
 
     /**
-     * This is a key set view of the {@link Trie} as returned by {@link Map#keySet()}.
+     * This is a key set view of the {@link org.apache.commons.collections4.Trie} as returned by {@link Map#keySet()}.
      */
     private class KeySet extends AbstractSet<K> {
 
@@ -1477,7 +1473,7 @@ public K next() {
     }
 
     /**
-     * This is a value view of the {@link Trie} as returned by {@link Map#values()}.
+     * This is a value view of the {@link org.apache.commons.collections4.Trie} as returned by {@link Map#values()}.
      */
     private class Values extends AbstractCollection<V> {
 
@@ -1598,7 +1594,7 @@ public void remove() {
     }
 
     /**
-     * An {@link OrderedMapIterator} for a {@link Trie}.
+     * An {@link OrderedMapIterator} for a {@link org.apache.commons.collections4.Trie}.
      */
     private class TrieMapIterator extends TrieIterator<K> implements OrderedMapIterator<K, V> {
 
@@ -1669,7 +1665,7 @@ protected TrieEntry<K, V> previousEntry() {
     }
 
     /**
-     * A range view of the {@link Trie}.
+     * A range view of the {@link org.apache.commons.collections4.Trie}.
      */
     private abstract class RangeMap extends AbstractMap<K, V>
             implements SortedMap<K, V> {
@@ -2077,7 +2073,7 @@ public Map.Entry<K, V> next() {
     }
 
     /**
-     * A submap used for prefix views over the {@link Trie}.
+     * A submap used for prefix views over the {@link org.apache.commons.collections4.Trie}.
      */
     private class PrefixRangeMap extends RangeMap {
 
@@ -2108,7 +2104,7 @@ private PrefixRangeMap(final K prefix, final int offsetInBits, final int lengthI
          * This method does two things. It determines the FROM
          * and TO range of the {@link PrefixRangeMap} and the number
          * of elements in the range. This method must be called every
-         * time the {@link Trie} has changed.
+         * time the {@link org.apache.commons.collections4.Trie} has changed.
          */
         private int fixup() {
             // The trie has changed since we last found our toKey / fromKey
@@ -2262,7 +2258,7 @@ public void clear() {
     }
 
     /**
-     * A prefix {@link RangeEntrySet} view of the {@link Trie}.
+     * A prefix {@link RangeEntrySet} view of the {@link org.apache.commons.collections4.Trie}.
      */
     private final class PrefixRangeEntrySet extends RangeEntrySet {