fixes misplaced symbols in javadoc (mainly in Hasher, CountingLongPre…

…dicate) (#409)

resolves grammar and punctuation issues

DEVELOPERS-GUIDE.html

@@ -98,7 +98,7 @@ <h3>4.  UTILITY CLASSES</h3>
 </ul>
 
 <p>Where the method in a Utils class is a decorator, the name shall consist of
-an adjective followed by the collection type.  Typically such adjective is
+an adjective followed by the collection type.  Typically, such adjective is
 formed by appending an -ed suffix (meaning "having"/"characterized by") to the
 word describing the type of decorator.  For example,
 <code>synchronizedMap(Map)</code> or <code>predicatedSet(Set)</code>.

src/main/java/org/apache/commons/collections4/MapUtils.java

@@ -1955,7 +1955,7 @@ public static void verbosePrint(final PrintStream out, final Object label, final
      * If the contents of a map include the map itself, then the text <em>(this Map)</em> is printed out. If the
      * contents include a parent container of the map, the text <em>(ancestor[i] Map)</em> is printed, where it actually
      * indicates the number of levels which must be traversed in the sequential list of ancestors (e.g. father,
-     * grandfather, great-grandfather, etc).
+     * grandfather, great-grandfather, etc.).
      *
      * @param out the stream to print to
      * @param label the label to be used, may be {@code null}. If {@code null}, the label is not output. It

src/main/java/org/apache/commons/collections4/MultiMap.java

@@ -123,7 +123,7 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
      * Adds the value to the collection associated with the specified key.
      * <p>
      * Unlike a normal {@code Map} the previous value is not replaced.
-     * Instead the new value is added to the collection stored against the key.
+     * 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.
      *

src/main/java/org/apache/commons/collections4/MultiSet.java

@@ -63,7 +63,7 @@ public interface MultiSet<E> extends Collection<E> {
      * Adds one copy of the specified object to the MultiSet.
      * <p>
      * If the object is already in the {@link #uniqueSet()} then increment its
-     * count as reported by {@link #getCount(Object)}. Otherwise add it to the
+     * count as reported by {@link #getCount(Object)}. Otherwise, add it to the
      * {@link #uniqueSet()} and report its count as 1.
      *
      * @param object  the object to add
@@ -77,7 +77,7 @@ public interface MultiSet<E> extends Collection<E> {
      * Adds a number of occurrences of the specified object to the MultiSet.
      * <p>
      * If the object is already in the {@link #uniqueSet()} then increment its
-     * count as reported by {@link #getCount(Object)}. Otherwise add it to the
+     * count as reported by {@link #getCount(Object)}. Otherwise, add it to the
      * {@link #uniqueSet()} and report its count as {@code occurrences}.
      *
      * @param object  the object to add

src/main/java/org/apache/commons/collections4/MultiValuedMap.java

@@ -120,7 +120,7 @@ public interface MultiValuedMap<K, V> {
      * Adds a key-value mapping to this multivalued map.
      * <p>
      * Unlike a normal {@code Map} the previous value is not replaced.
-     * Instead the new value is added to the collection stored against the key.
+     * Instead, the new value is added to the collection stored against the key.
      * Depending on the collection type used, duplicate key-value mappings may
      * be allowed.
      * <p>

src/main/java/org/apache/commons/collections4/PredicateUtils.java

@@ -447,8 +447,8 @@ public static <T> Predicate<T> notPredicate(final Predicate<? super T> predicate
 
     /**
      * Create a new Predicate that wraps a Transformer. The Transformer must
-     * return either Boolean.TRUE or Boolean.FALSE otherwise a PredicateException
-     * will be thrown.
+     * return either {@link Boolean#TRUE} or {@link Boolean#FALSE} otherwise a
+     * PredicateException will be thrown.
      *
      * @param <T>  the type that the predicate queries
      * @param transformer  the transformer to wrap, may not be null

src/main/java/org/apache/commons/collections4/SplitMapUtils.java

@@ -223,7 +223,7 @@ public Collection<V> values() {
      * Get the specified {@link Get} as an instance of {@link IterableMap}.
      * 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.
+     * 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
@@ -244,7 +244,7 @@ public static <K, V> IterableMap<K, V> readableMap(final Get<K, V> get) {
     /**
      * Get the specified {@link Put} as an instanceof {@link Map}.
      * If {@code put} implements {@link Map} directly, no conversion will take place.
-     * Otherwise a <em>write-only</em> {@link Map} will be returned.  On such a {@link Map}
+     * Otherwise, a <em>write-only</em> {@link Map} will be returned.  On such a {@link Map}
      * it is recommended that the result of #put(K, V) be discarded as it likely will not
      * match {@code V} at runtime.
      *

src/main/java/org/apache/commons/collections4/TransformerUtils.java

@@ -161,7 +161,7 @@ public static <T> Transformer<T, T> asTransformer(final Closure<? super T> closu
 
     /**
      * Creates a Transformer that calls a Predicate each time the transformer is used.
-     * The transformer will return either Boolean.TRUE or Boolean.FALSE.
+     * The transformer will return either {@link Boolean#TRUE} or {@link Boolean#FALSE}.
      *
      * @param <T>  the input type
      * @param predicate  the predicate to run each time in the transformer, not null

src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java

@@ -180,7 +180,7 @@ public boolean addAll(final Collection<? extends E> coll) {
      * <p>
      * Create a Builder with a predicate to validate elements against, then add any elements
      * to the builder. Elements that fail the predicate will be added to a rejected list.
-     * Finally create or decorate a collection using the createPredicated[List,Set,Bag,Queue] methods.
+     * Finally, create or decorate a collection using the createPredicated[List,Set,Bag,Queue] methods.
      * <p>
      * An example:
      * <pre>
@@ -193,7 +193,7 @@ public boolean addAll(final Collection<? extends E> coll) {
      * </pre>
      * <p>
      * At the end of the code fragment above predicatedList is protected by the predicate supplied
-     * to the builder and it contains item1 and item2.
+     * to the builder, and it contains item1 and item2.
      * <p>
      * More elements can be added to the builder once a predicated collection has been created,
      * but these elements will not be reflected in already created collections.

src/main/java/org/apache/commons/collections4/functors/WhileClosure.java

@@ -47,7 +47,7 @@ public class WhileClosure<E> implements Closure<E> {
      *
      * @param <E> the type that the closure acts on
      * @param predicate  the predicate used to evaluate when the loop terminates, not null
-     * @param closure  the closure the execute, not null
+     * @param closure  the closure to execute, not null
      * @param doLoop  true to act as a do-while loop, always executing the closure once
      * @return the {@code while} closure
      * @throws NullPointerException if the predicate or closure is null
@@ -63,7 +63,7 @@ public static <E> Closure<E> whileClosure(final Predicate<? super E> predicate,
      * Use {@code whileClosure} if you want that.
      *
      * @param predicate  the predicate used to evaluate when the loop terminates, not null
-     * @param closure  the closure the execute, not null
+     * @param closure  the closure to execute, not null
      * @param doLoop  true to act as a do-while loop, always executing the closure once
      */
     public WhileClosure(final Predicate<? super E> predicate, final Closure<? super E> closure, final boolean doLoop) {

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

@@ -41,7 +41,7 @@
  * this case the class will function as an empty iterator.
  * <p>
  * NOTE: As from version 4.0, the IteratorChain stores the iterators in a queue
- * and removes any reference to them as soon as they are not used anymore. Thus
+ * and removes any reference to them as soon as they are not used anymore. Thus,
  * the methods {@code setIterator(Iterator)} and {@code getIterators()} have been
  * removed and {@link #size()} will return the number of remaining iterators in
  * the queue.

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

@@ -43,7 +43,7 @@ public class NodeListIterator implements Iterator<Node> {
      * Convenience constructor, which creates a new NodeListIterator from
      * the specified node's childNodes.
      *
-     * @param node Node, who's child nodes are wrapped by this class. Must not be null
+     * @param node Node, whose child nodes are wrapped by this class. Must not be null
      * @throws NullPointerException if node is null
      */
     public NodeListIterator(final Node node) {

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

@@ -228,7 +228,7 @@ public E next() {
     /**
      * Removes from the underlying collection the last element returned.
      * <p>
-     * This method calls remove() on the underlying Iterator and it may
+     * This method calls remove() on the underlying Iterator, and it may
      * throw an UnsupportedOperationException if the underlying Iterator
      * does not support this method.
      *

src/main/java/org/apache/commons/collections4/list/CursorableLinkedList.java

@@ -285,7 +285,7 @@ protected void unregisterCursor(final Cursor<E> cursor) {
             if (cur == null) {
                 // some other unrelated cursor object has been
                 // garbage-collected; let's take the opportunity to
-                // clean up the cursors list anyway..
+                // clean up the cursors list anyway.
                 it.remove();
             } else if (cur == cursor) {
                 ref.clear();

src/main/java/org/apache/commons/collections4/list/NodeCachingLinkedList.java

@@ -154,7 +154,7 @@ protected boolean isCacheFull() {
 
     /**
      * Adds a node to the cache, if the cache isn't full.
-     * The node's contents are cleared so they can be garbage collected.
+     * The node's contents are cleared, so they can be garbage collected.
      *
      * @param node  the node to add to the cache
      */

src/main/java/org/apache/commons/collections4/list/SetUniqueList.java

@@ -112,7 +112,7 @@ public Set<E> asSet() {
      * Adds an element to the list if it is not already present.
      * <p>
      * <i>(Violation)</i> The {@code List} interface requires that this
-     * method returns {@code true} always. However this class may return
+     * method returns {@code true} always. However, this class may return
      * {@code false} because of the {@code Set} behavior.
      *
      * @param object  the object to add

src/main/java/org/apache/commons/collections4/list/TreeList.java

@@ -210,7 +210,7 @@ public void add(final int index, final E obj) {
     }
 
     /**
-     * Appends all of the elements in the specified collection to the end of this list,
+     * Appends all the elements in the specified collection to the end of this list,
      * in the order that they are returned by the specified collection's Iterator.
      * <p>
      * This method runs in O(n + log m) time, where m is

src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java

@@ -435,7 +435,7 @@ public V setValue(final int index, final V value) {
      * The remove may change the effect of the index. The index is
      * always calculated relative to the original state of the map.
      * <p>
-     * Thus the steps are: (1) remove the existing key-value mapping,
+     * Thus, the steps are: (1) remove the existing key-value mapping,
      * then (2) insert the new key-value mapping at the position it
      * would have been inserted had the remove not occurred.
      *

src/main/java/org/apache/commons/collections4/map/MultiValueMap.java

@@ -252,7 +252,7 @@ public boolean containsValue(final Object value) {
      * Adds the value to the collection associated with the specified key.
      * <p>
      * Unlike a normal {@code Map} the previous value is not replaced.
-     * Instead the new value is added to the collection stored against the key.
+     * Instead, the new value is added to the collection stored against the key.
      *
      * @param key  the key to store against
      * @param value  the value to add to the collection at the key

src/main/java/org/apache/commons/collections4/sequence/SequencesComparator.java

@@ -162,9 +162,9 @@ private Snake buildSnake(final int start, final int diag, final int end1, final
      * <a href="https://web.archive.org/web/20040719035900/http%3A//www.cs.arizona.edu/people/gene/PAPERS/diff.ps">
      * An O(ND) Difference Algorithm and Its Variations</a>.
      *
-     * @param start1  the begin of the first sequence to be compared
+     * @param start1  the start of the first sequence to be compared
      * @param end1  the end of the first sequence to be compared
-     * @param start2  the begin of the second sequence to be compared
+     * @param start2  the start of the second sequence to be compared
      * @param end2  the end of the second sequence to be compared
      * @return the middle snake
      */
@@ -241,9 +241,9 @@ private Snake getMiddleSnake(final int start1, final int end1, final int start2,
     /**
      * Build an edit script.
      *
-     * @param start1  the begin of the first sequence to be compared
+     * @param start1  the start of the first sequence to be compared
      * @param end1  the end of the first sequence to be compared
-     * @param start2  the begin of the second sequence to be compared
+     * @param start2  the start of the second sequence to be compared
      * @param end2  the end of the second sequence to be compared
      * @param script the edited script
      */

src/main/java/org/apache/commons/collections4/sequence/package-info.java

@@ -56,7 +56,7 @@
  * to perform the transformation, of course, or to retrieve the longest
  * common subsequence for example.
  * <p>
- * If the user needs a very fine-grained access to the comparison result,
+ * If the user needs very fine-grained access to the comparison result,
  * he needs to go through this script by providing a visitor implementing
  * the {@link org.apache.commons.collections4.sequence.CommandVisitor} interface.
  * <p>

src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java

@@ -46,7 +46,7 @@ public abstract class KeyAnalyzer<K> implements Comparator<K>, Serializable {
 
     /**
      * Returned by {@link #bitIndex(Object, int, int, Object, int, int)} if key and found key are equal.
-     * This is a very very specific case and shouldn't happen on a regular basis.
+     * This is a very, very specific case and shouldn't happen on a regular basis.
      */
     public static final int EQUAL_BIT_KEY = -2;
 

src/site/xdoc/history.xml

@@ -56,7 +56,7 @@ behave like the unmodifiable or synchronized JDK decorators.
 </p>
 <p>
 As the size of the component increased, the iterators were broken out into their own subpackage.
-Thus there were now three packages, main, comparator and iterator.
+Thus, there were now three packages, main, comparator and iterator.
 </p>
 
 <p>
@@ -85,7 +85,7 @@ Of course, backwards compatibility has been retained during all transitions usin
 <p>
 <b>Collections 2.1.1</b> was a patch release to version 2.1.
 Unfortunately, version 3.0 created a <a href="compatibility.html">binary incompatibility</a> in the IteratorUtils class.
-This patch was created as a work around, enabling 2.1.1 to be compatible with 3.1.
+This patch was created as a workaround, enabling 2.1.1 to be compatible with 3.1.
 </p>
 
 <p>