This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-collections.git
commit 2ae865abc2a70e5b7f6af99374d2c61ad5646814 Author: Gary Gregory <[email protected]> AuthorDate: Sun Aug 25 17:54:17 2024 -0400 Javadoc --- .../collections4/bidimap/DualTreeBidiMap.java | 11 ++++++ .../comparators/FixedOrderComparator.java | 19 ++++++++-- .../collections4/functors/ComparatorPredicate.java | 31 +++++++++++++++-- .../collections4/list/AbstractLinkedList.java | 25 +++++++++++--- .../collections4/map/AbstractHashedMap.java | 40 ++++++++++++++++++++++ .../collections4/map/AbstractReferenceMap.java | 18 ++++++++-- .../collections4/trie/AbstractBitwiseTrie.java | 10 ++++++ .../collections4/trie/AbstractPatriciaTrie.java | 34 ++++++++++++------ .../commons/collections4/trie/KeyAnalyzer.java | 5 ++- .../collections4/trie/UnmodifiableTrie.java | 3 ++ 10 files changed, 173 insertions(+), 23 deletions(-) diff --git a/src/main/java/org/apache/commons/collections4/bidimap/DualTreeBidiMap.java b/src/main/java/org/apache/commons/collections4/bidimap/DualTreeBidiMap.java index 50d49d5d7..5d51c62db 100644 --- a/src/main/java/org/apache/commons/collections4/bidimap/DualTreeBidiMap.java +++ b/src/main/java/org/apache/commons/collections4/bidimap/DualTreeBidiMap.java @@ -322,10 +322,20 @@ public class DualTreeBidiMap<K, V> extends AbstractDualBidiMap<K, V> return (SortedBidiMap<V, K>) super.inverseBidiMap(); } + /** + * Defaults to {@link #inverseBidiMap()}. + * + * @return Defaults to {@link #inverseBidiMap()}. + */ public OrderedBidiMap<V, K> inverseOrderedBidiMap() { return inverseBidiMap(); } + /** + * Defaults to {@link #inverseBidiMap()}. + * + * @return Defaults to {@link #inverseBidiMap()}. + */ public SortedBidiMap<V, K> inverseSortedBidiMap() { return inverseBidiMap(); } @@ -340,6 +350,7 @@ public class DualTreeBidiMap<K, V> extends AbstractDualBidiMap<K, V> * <p> * This implementation copies the elements to an ArrayList in order to * provide the forward/backward behavior. + * </p> * * @return a new ordered map iterator */ diff --git a/src/main/java/org/apache/commons/collections4/comparators/FixedOrderComparator.java b/src/main/java/org/apache/commons/collections4/comparators/FixedOrderComparator.java index 6cd77f3c5..0952beea0 100644 --- a/src/main/java/org/apache/commons/collections4/comparators/FixedOrderComparator.java +++ b/src/main/java/org/apache/commons/collections4/comparators/FixedOrderComparator.java @@ -53,11 +53,26 @@ import java.util.Objects; public class FixedOrderComparator<T> implements Comparator<T>, Serializable { /** - * Unknown object behavior enum. + * Enumerates the unknown object behaviors. + * * @since 4.0 */ public enum UnknownObjectBehavior { - BEFORE, AFTER, EXCEPTION + + /** + * Before unknown object behaviors. + */ + BEFORE, + + /** + * After unknown object behaviors. + */ + AFTER, + + /** + * Exception unknown object behaviors. + */ + EXCEPTION } /** Serialization version from Collections 4.0. */ diff --git a/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java b/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java index d42cb9732..8c8aca39e 100644 --- a/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java +++ b/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java @@ -79,14 +79,39 @@ import org.apache.commons.collections4.Predicate; */ public class ComparatorPredicate<T> extends AbstractPredicate<T> implements Serializable { + /** + * Enumerates the comparator criteria. + */ public enum Criterion { - EQUAL, GREATER, LESS, GREATER_OR_EQUAL, LESS_OR_EQUAL, + + /** + * Equal criterion. + */ + EQUAL, + + /** + * Greater criterion. + */ + GREATER, + + /** + * Less criterion. + */ + LESS, + + /** + * Greater or equal criterion. + */ + GREATER_OR_EQUAL, + + /** + * Less or equal Criterion. + */ + LESS_OR_EQUAL, } private static final long serialVersionUID = -1863209236504077399L; - // Instance variables: - /** * Factory to create the comparator predicate * diff --git a/src/main/java/org/apache/commons/collections4/list/AbstractLinkedList.java b/src/main/java/org/apache/commons/collections4/list/AbstractLinkedList.java index 0a941b6e4..68353e82b 100644 --- a/src/main/java/org/apache/commons/collections4/list/AbstractLinkedList.java +++ b/src/main/java/org/apache/commons/collections4/list/AbstractLinkedList.java @@ -101,9 +101,9 @@ public abstract class AbstractLinkedList<E> implements List<E> { /** * Create a ListIterator for a list. * - * @param parent the parent list - * @param fromIndex the index to start at - * @throws IndexOutOfBoundsException if fromIndex is less than 0 or greater than the size of the list + * @param parent the parent list. + * @param fromIndex The starting index. + * @throws IndexOutOfBoundsException if fromIndex is less than 0 or greater than the size of the list. */ protected LinkedListIterator(final AbstractLinkedList<E> parent, final int fromIndex) throws IndexOutOfBoundsException { @@ -226,15 +226,26 @@ public abstract class AbstractLinkedList<E> implements List<E> { * @param <E> the type of elements in this list. */ protected static class LinkedSubList<E> extends AbstractList<E> { + /** The main list */ AbstractLinkedList<E> parent; + /** Offset from the main list */ int offset; + /** Sublist size */ int size; + /** Sublist modCount */ int expectedModCount; + /** + * Constructs a new instance. + * + * @param parent The parent AbstractLinkedList. + * @param fromIndex An index greater or equal to 0 and less than {@code toIndex}. + * @param toIndex An index greater than {@code fromIndex}. + */ protected LinkedSubList(final AbstractLinkedList<E> parent, final int fromIndex, final int toIndex) { if (fromIndex < 0) { throw new IndexOutOfBoundsException("fromIndex = " + fromIndex); @@ -361,9 +372,15 @@ public abstract class AbstractLinkedList<E> implements List<E> { */ protected static class LinkedSubListIterator<E> extends LinkedListIterator<E> { - /** The sub list */ + /** The sub list. */ protected final LinkedSubList<E> sub; + /** + * Constructs a new instance. + * + * @param sub The sub-list. + * @param startIndex The starting index. + */ protected LinkedSubListIterator(final LinkedSubList<E> sub, final int startIndex) { super(sub.parent, startIndex + sub.offset); this.sub = sub; diff --git a/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java b/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java index 8994c36d7..fcc86d401 100644 --- a/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java +++ b/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java @@ -168,6 +168,14 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab /** The value */ protected Object value; + /** + * Constructs a new instance. + * + * @param next next. + * @param hashCode hash code. + * @param key key. + * @param value value. + */ protected HashEntry(final HashEntry<K, V> next, final int hashCode, final Object key, final V value) { this.next = next; this.hashCode = hashCode; @@ -246,6 +254,11 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab /** The modification count expected */ private int expectedModCount; + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected HashIterator(final AbstractHashedMap<K, V> parent) { this.parent = parent; final HashEntry<K, V>[] data = parent.data; @@ -316,6 +329,11 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab */ protected static class HashMapIterator<K, V> extends HashIterator<K, V> implements MapIterator<K, V> { + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected HashMapIterator(final AbstractHashedMap<K, V> parent) { super(parent); } @@ -359,9 +377,15 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab * @param <K> the type of elements maintained by this set */ protected static class KeySet<K> extends AbstractSet<K> { + /** The parent map */ private final AbstractHashedMap<K, ?> parent; + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected KeySet(final AbstractHashedMap<K, ?> parent) { this.parent = parent; } @@ -401,6 +425,11 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab */ protected static class KeySetIterator<K> extends HashIterator<K, Object> implements Iterator<K> { + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ @SuppressWarnings("unchecked") protected KeySetIterator(final AbstractHashedMap<K, ?> parent) { super((AbstractHashedMap<K, Object>) parent); @@ -418,9 +447,15 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab * @param <V> the type of elements maintained by this collection */ protected static class Values<V> extends AbstractCollection<V> { + /** The parent map */ private final AbstractHashedMap<?, V> parent; + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected Values(final AbstractHashedMap<?, V> parent) { this.parent = parent; } @@ -453,6 +488,11 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K, V> implements Iterab */ protected static class ValuesIterator<V> extends HashIterator<Object, V> implements Iterator<V> { + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ @SuppressWarnings("unchecked") protected ValuesIterator(final AbstractHashedMap<?, V> parent) { super((AbstractHashedMap<Object, V>) parent); diff --git a/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java b/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java index 7ff279752..b6863b4c2 100644 --- a/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java +++ b/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java @@ -495,10 +495,24 @@ public abstract class AbstractReferenceMap<K, V> extends AbstractHashedMap<K, V> } /** - * Reference type enum. + * Enumerates reference types. */ public enum ReferenceStrength { - HARD(0), SOFT(1), WEAK(2); + + /** + * Hard reference type. + */ + HARD(0), + + /** + * Soft reference type. + */ + SOFT(1), + + /** + * Weak reference type. + */ + WEAK(2); /** * Resolve enum from int. diff --git a/src/main/java/org/apache/commons/collections4/trie/AbstractBitwiseTrie.java b/src/main/java/org/apache/commons/collections4/trie/AbstractBitwiseTrie.java index 22445e4b1..bb87e0a5c 100644 --- a/src/main/java/org/apache/commons/collections4/trie/AbstractBitwiseTrie.java +++ b/src/main/java/org/apache/commons/collections4/trie/AbstractBitwiseTrie.java @@ -41,8 +41,14 @@ public abstract class AbstractBitwiseTrie<K, V> extends AbstractMap<K, V> private static final long serialVersionUID = -944364551314110330L; + /** + * The entry's key. + */ protected K key; + /** + * The entry's value. + */ protected V value; BasicEntry(final K key) { @@ -89,6 +95,10 @@ public abstract class AbstractBitwiseTrie<K, V> extends AbstractMap<K, V> /** * Replaces the current key and value with the provided key & value. + * + * @param key The new key. + * @param value The new value. + * @return The previous value. */ public V setKeyValue(final K key, final V value) { this.key = key; diff --git a/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java b/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java index ea3d3801a..55175c9e9 100644 --- a/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java +++ b/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java @@ -996,11 +996,16 @@ public abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, /** The entry who uplinks to this entry. */ protected TrieEntry<K, V> predecessor; + /** + * Constructs a new instance. + * + * @param key The entry's key. + * @param value The entry's value. + * @param bitIndex The entry's bitIndex. + */ public TrieEntry(final K key, final V value, final int bitIndex) { super(key, value); - this.bitIndex = bitIndex; - this.parent = null; this.left = this; this.right = null; @@ -1008,23 +1013,29 @@ public abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, } /** - * Whether or not the entry is storing a key. + * Whether the entry is storing a key. * Only the root can potentially be empty, all other * nodes must have a key. + * + * @return Whether the entry is storing a key */ public boolean isEmpty() { return key == null; } /** - * Either the left or right child is a loopback. + * Whether the left or right child is a loopback. + * + * @return Whether the left or right child is a loopback. */ public boolean isExternalNode() { return !isInternalNode(); } /** - * Neither the left nor right child is a loopback. + * Tests that neither the left nor right child is a loopback. + * + * @return That neither the left nor right child is a loopback. */ public boolean isInternalNode() { return left != this && right != this; @@ -1245,19 +1256,20 @@ public abstract class AbstractPatriciaTrie<K, V> extends AbstractBitwiseTrie<K, /** * Constructs a new {@link Trie} using the given {@link KeyAnalyzer}. * - * @param keyAnalyzer the {@link KeyAnalyzer} to use + * @param keyAnalyzer the {@link KeyAnalyzer}. */ protected AbstractPatriciaTrie(final KeyAnalyzer<? super K> keyAnalyzer) { super(keyAnalyzer); } /** - * 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}. + * 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}. + * + * @param keyAnalyzer the {@link KeyAnalyzer}. + * @param map The source map. */ - protected AbstractPatriciaTrie(final KeyAnalyzer<? super K> keyAnalyzer, - final Map<? extends K, ? extends V> map) { + protected AbstractPatriciaTrie(final KeyAnalyzer<? super K> keyAnalyzer, final Map<? extends K, ? extends V> map) { super(keyAnalyzer); putAll(map); } diff --git a/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java index 9b8c8fef6..a6dfd7707 100644 --- a/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java @@ -46,10 +46,13 @@ 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 specific case and shouldn't happen on a regular basis. */ public static final int EQUAL_BIT_KEY = -2; + /** + * Used to test a {@code bitIndex} in {@link #isOutOfBoundsIndex(int)}. + */ public static final int OUT_OF_BOUNDS_BIT_KEY = -3; /** diff --git a/src/main/java/org/apache/commons/collections4/trie/UnmodifiableTrie.java b/src/main/java/org/apache/commons/collections4/trie/UnmodifiableTrie.java index f89b23cd6..122330b7e 100644 --- a/src/main/java/org/apache/commons/collections4/trie/UnmodifiableTrie.java +++ b/src/main/java/org/apache/commons/collections4/trie/UnmodifiableTrie.java @@ -60,6 +60,9 @@ public class UnmodifiableTrie<K, V> implements Trie<K, V>, Serializable, Unmodif return new UnmodifiableTrie<>(trie); } + /** + * The delegate Trie. + */ private final Trie<K, V> delegate; /**
