From 775886ba0cb54d700268f236796c86603037951d Mon Sep 17 00:00:00 2001 From: Stephan Fuhrmann Date: Fri, 15 Jun 2018 16:26:27 -0600 Subject: [PATCH] Javadoc fixes. Closes #43. --- .../commons/collections4/IterableUtils.java | 2 +- .../collections4/bidimap/TreeBidiMap.java | 93 ++++++++++++------- .../collections4/functors/FunctorUtils.java | 3 +- .../iterators/LazyIteratorChain.java | 2 +- .../commons/collections4/map/Flat3Map.java | 2 +- 5 files changed, 64 insertions(+), 38 deletions(-) diff --git a/src/main/java/org/apache/commons/collections4/IterableUtils.java b/src/main/java/org/apache/commons/collections4/IterableUtils.java index 104f4d135..05613c5e2 100644 --- a/src/main/java/org/apache/commons/collections4/IterableUtils.java +++ b/src/main/java/org/apache/commons/collections4/IterableUtils.java @@ -1074,7 +1074,7 @@ public class IterableUtils { /** * Fail-fast check for null arguments. * - * @param iterable the iterable to check + * @param iterables the iterables to check * @throws NullPointerException if the argument or any of its contents is null */ static void checkNotNull(final Iterable... iterables) { diff --git a/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java b/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java index c281f940b..33d1943ff 100644 --- a/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java +++ b/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java @@ -579,7 +579,8 @@ public class TreeBidiMap, V extends Comparable> * do the actual lookup of a piece of data * * @param data the key or value to be looked up - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the desired Node, or null if there is no mapping of the * specified data */ @@ -612,7 +613,8 @@ public class TreeBidiMap, V extends Comparable> * get the next larger node from the specified node * * @param node the node to be searched from - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the specified node */ private Node nextGreater(final Node node, final DataElement dataElement) { @@ -646,7 +648,8 @@ public class TreeBidiMap, V extends Comparable> * get the next larger node from the specified node * * @param node the node to be searched from - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the specified node */ private Node nextSmaller(final Node node, final DataElement dataElement) { @@ -695,7 +698,8 @@ public class TreeBidiMap, V extends Comparable> * Find the least node from a given node. * * @param node the node from which we will start searching - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the smallest node, from the specified node, in the * specified mapping */ @@ -713,7 +717,8 @@ public class TreeBidiMap, V extends Comparable> * Find the greatest node from a given node. * * @param node the node from which we will start searching - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the greatest node, from the specified node */ private Node greatestNode(final Node node, final DataElement dataElement) { @@ -732,7 +737,8 @@ public class TreeBidiMap, V extends Comparable> * * @param from the node whose color we're copying; may be null * @param to the node whose color we're changing; may be null - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void copyColor(final Node from, final Node to, final DataElement dataElement) { if (to != null) { @@ -750,7 +756,8 @@ public class TreeBidiMap, V extends Comparable> * black, thank you * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private static boolean isRed(final Node node, final DataElement dataElement) { return node != null && node.isRed(dataElement); @@ -761,7 +768,8 @@ public class TreeBidiMap, V extends Comparable> * it's black, thank you * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private static boolean isBlack(final Node node, final DataElement dataElement) { return node == null || node.isBlack(dataElement); @@ -771,7 +779,8 @@ public class TreeBidiMap, V extends Comparable> * force a node (if it exists) red * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private static void makeRed(final Node node, final DataElement dataElement) { if (node != null) { @@ -783,7 +792,8 @@ public class TreeBidiMap, V extends Comparable> * force a node (if it exists) black * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private static void makeBlack(final Node node, final DataElement dataElement) { if (node != null) { @@ -796,7 +806,8 @@ public class TreeBidiMap, V extends Comparable> * its grandparent may not exist. no problem * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private Node getGrandParent(final Node node, final DataElement dataElement) { return getParent(getParent(node, dataElement), dataElement); @@ -807,7 +818,8 @@ public class TreeBidiMap, V extends Comparable> * exist. no problem * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private Node getParent(final Node node, final DataElement dataElement) { return node == null ? null : node.getParent(dataElement); @@ -818,7 +830,8 @@ public class TreeBidiMap, V extends Comparable> * problem * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private Node getRightChild(final Node node, final DataElement dataElement) { return node == null ? null : node.getRight(dataElement); @@ -829,7 +842,8 @@ public class TreeBidiMap, V extends Comparable> * problem * * @param node the node (may be null) in question - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private Node getLeftChild(final Node node, final DataElement dataElement) { return node == null ? null : node.getLeft(dataElement); @@ -839,7 +853,8 @@ public class TreeBidiMap, V extends Comparable> * do a rotate left. standard fare in the world of balanced trees * * @param node the node to be rotated - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void rotateLeft(final Node node, final DataElement dataElement) { final Node rightChild = node.getRight(dataElement); @@ -867,7 +882,8 @@ public class TreeBidiMap, V extends Comparable> * do a rotate right. standard fare in the world of balanced trees * * @param node the node to be rotated - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void rotateRight(final Node node, final DataElement dataElement) { final Node leftChild = node.getLeft(dataElement); @@ -1212,8 +1228,8 @@ public class TreeBidiMap, V extends Comparable> * Comparable and non-null * * @param o the object being checked - * @param index the KEY or VALUE int (used to put the right word in the - * exception message) + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * * @throws NullPointerException if o is null * @throws ClassCastException if o is not Comparable @@ -1337,7 +1353,8 @@ public class TreeBidiMap, V extends Comparable> * Compares for equals as per the API. * * @param obj the object to compare to - * @param type the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return true if equal */ private boolean doEquals(final Object obj, final DataElement dataElement) { @@ -1373,7 +1390,8 @@ public class TreeBidiMap, V extends Comparable> /** * Gets the hash code value for this map as per the API. * - * @param type the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the hash code value for this map */ private int doHashCode(final DataElement dataElement) { @@ -1391,7 +1409,8 @@ public class TreeBidiMap, V extends Comparable> /** * Gets the string form of this map as per AbstractMap. * - * @param type the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the string form of this map */ private String doToString(final DataElement dataElement) { @@ -1476,7 +1495,6 @@ public class TreeBidiMap, V extends Comparable> /** * Constructor. * @param orderType the KEY or VALUE int for the order - * @param main the main map */ View(final DataElement orderType) { super(); @@ -1650,7 +1668,6 @@ public class TreeBidiMap, V extends Comparable> /** * Constructor. * @param orderType the KEY or VALUE int for the order - * @param main the main map */ ViewIterator(final DataElement orderType) { super(); @@ -1879,8 +1896,8 @@ public class TreeBidiMap, V extends Comparable> * Make a new cell with given key and value, and with null * links, and black (true) colors. * - * @param key - * @param value + * @param key the key of this node + * @param value the value of this node */ @SuppressWarnings("unchecked") Node(final K key, final V value) { @@ -1925,7 +1942,8 @@ public class TreeBidiMap, V extends Comparable> * Set this node's parent node. * * @param node the new parent node - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void setParent(final Node node, final DataElement dataElement) { parentNode[dataElement.ordinal()] = node; @@ -1934,7 +1952,8 @@ public class TreeBidiMap, V extends Comparable> /** * Get the parent node. * - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return the parent node, may be null */ private Node getParent(final DataElement dataElement) { @@ -1945,7 +1964,8 @@ public class TreeBidiMap, V extends Comparable> * Exchange colors with another node. * * @param node the node to swap with - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void swapColors(final Node node, final DataElement dataElement) { // Swap colors -- old hacker's trick @@ -1957,7 +1977,8 @@ public class TreeBidiMap, V extends Comparable> /** * Is this node black? * - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return true if black (which is represented as a true boolean) */ private boolean isBlack(final DataElement dataElement) { @@ -1967,7 +1988,8 @@ public class TreeBidiMap, V extends Comparable> /** * Is this node red? * - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. * @return true if non-black */ private boolean isRed(final DataElement dataElement) { @@ -1977,7 +1999,8 @@ public class TreeBidiMap, V extends Comparable> /** * Make this node black. * - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void setBlack(final DataElement dataElement) { blackColor[dataElement.ordinal()] = true; @@ -1986,7 +2009,8 @@ public class TreeBidiMap, V extends Comparable> /** * Make this node red. * - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void setRed(final DataElement dataElement) { blackColor[dataElement.ordinal()] = false; @@ -1996,7 +2020,8 @@ public class TreeBidiMap, V extends Comparable> * Make this node the same color as another * * @param node the node whose color we're adopting - * @param index the KEY or VALUE int + * @param dataElement either {@link DataElement#KEY} key} + * or the {@link DataElement#VALUE value}. */ private void copyColor(final Node node, final DataElement dataElement) { blackColor[dataElement.ordinal()] = node.blackColor[dataElement.ordinal()]; @@ -2036,7 +2061,7 @@ public class TreeBidiMap, V extends Comparable> /** * Optional operation that is not permitted in this implementation * - * @param ignored + * @param ignored this parameter is ignored. * @return does not return * @throws UnsupportedOperationException always */ diff --git a/src/main/java/org/apache/commons/collections4/functors/FunctorUtils.java b/src/main/java/org/apache/commons/collections4/functors/FunctorUtils.java index 1efc2d517..77b266ed7 100644 --- a/src/main/java/org/apache/commons/collections4/functors/FunctorUtils.java +++ b/src/main/java/org/apache/commons/collections4/functors/FunctorUtils.java @@ -194,7 +194,8 @@ class FunctorUtils { * simply as centralised documentation and atomic unchecked warning * suppression. * - * @param the type of object the returned transformer should "accept" + * @param the type of object the returned transformer should "accept" + * @param the type of object the returned transformer should "produce" * @param transformer the transformer to coerce. * @return the coerced transformer. */ diff --git a/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java b/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java index 733a696b4..780e1fd19 100644 --- a/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java +++ b/src/main/java/org/apache/commons/collections4/iterators/LazyIteratorChain.java @@ -47,7 +47,7 @@ import java.util.Iterator; */ public abstract class LazyIteratorChain implements Iterator { - /** The number of times {@link #nextIterator()} was already called. */ + /** The number of times {@link #next()} was already called. */ private int callCounter = 0; /** Indicates that the Iterator chain has been exhausted. */ diff --git a/src/main/java/org/apache/commons/collections4/map/Flat3Map.java b/src/main/java/org/apache/commons/collections4/map/Flat3Map.java index aded12591..00a5d6b5a 100644 --- a/src/main/java/org/apache/commons/collections4/map/Flat3Map.java +++ b/src/main/java/org/apache/commons/collections4/map/Flat3Map.java @@ -815,7 +815,7 @@ public class Flat3Map implements IterableMap, Serializable, Cloneabl * As a consequence, all subsequent call to {@link #getKey()}, * {@link #setValue(Object)} and {@link #getValue()} will fail. * - * @param flag + * @param flag the new value of the removed flag */ void setRemoved(final boolean flag) { this.removed = flag;