From 2ae865abc2a70e5b7f6af99374d2c61ad5646814 Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sun, 25 Aug 2024 17:54:17 -0400 Subject: [PATCH] Javadoc --- .../collections4/bidimap/DualTreeBidiMap.java | 11 +++++ .../comparators/FixedOrderComparator.java | 19 ++++++++- .../functors/ComparatorPredicate.java | 31 ++++++++++++-- .../collections4/list/AbstractLinkedList.java | 25 ++++++++++-- .../collections4/map/AbstractHashedMap.java | 40 +++++++++++++++++++ .../map/AbstractReferenceMap.java | 18 ++++++++- .../trie/AbstractBitwiseTrie.java | 10 +++++ .../trie/AbstractPatriciaTrie.java | 34 +++++++++++----- .../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 extends AbstractDualBidiMap return (SortedBidiMap) super.inverseBidiMap(); } + /** + * Defaults to {@link #inverseBidiMap()}. + * + * @return Defaults to {@link #inverseBidiMap()}. + */ public OrderedBidiMap inverseOrderedBidiMap() { return inverseBidiMap(); } + /** + * Defaults to {@link #inverseBidiMap()}. + * + * @return Defaults to {@link #inverseBidiMap()}. + */ public SortedBidiMap inverseSortedBidiMap() { return inverseBidiMap(); } @@ -340,6 +350,7 @@ public class DualTreeBidiMap extends AbstractDualBidiMap *

* This implementation copies the elements to an ArrayList in order to * provide the forward/backward behavior. + *

* * @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 implements Comparator, 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 extends AbstractPredicate 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 implements List { /** * 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 parent, final int fromIndex) throws IndexOutOfBoundsException { @@ -226,15 +226,26 @@ public abstract class AbstractLinkedList implements List { * @param the type of elements in this list. */ protected static class LinkedSubList extends AbstractList { + /** The main list */ AbstractLinkedList 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 parent, final int fromIndex, final int toIndex) { if (fromIndex < 0) { throw new IndexOutOfBoundsException("fromIndex = " + fromIndex); @@ -361,9 +372,15 @@ public abstract class AbstractLinkedList implements List { */ protected static class LinkedSubListIterator extends LinkedListIterator { - /** The sub list */ + /** The sub list. */ protected final LinkedSubList sub; + /** + * Constructs a new instance. + * + * @param sub The sub-list. + * @param startIndex The starting index. + */ protected LinkedSubListIterator(final LinkedSubList 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 extends AbstractMap 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 next, final int hashCode, final Object key, final V value) { this.next = next; this.hashCode = hashCode; @@ -246,6 +254,11 @@ public class AbstractHashedMap extends AbstractMap implements Iterab /** The modification count expected */ private int expectedModCount; + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected HashIterator(final AbstractHashedMap parent) { this.parent = parent; final HashEntry[] data = parent.data; @@ -316,6 +329,11 @@ public class AbstractHashedMap extends AbstractMap implements Iterab */ protected static class HashMapIterator extends HashIterator implements MapIterator { + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected HashMapIterator(final AbstractHashedMap parent) { super(parent); } @@ -359,9 +377,15 @@ public class AbstractHashedMap extends AbstractMap implements Iterab * @param the type of elements maintained by this set */ protected static class KeySet extends AbstractSet { + /** The parent map */ private final AbstractHashedMap parent; + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected KeySet(final AbstractHashedMap parent) { this.parent = parent; } @@ -401,6 +425,11 @@ public class AbstractHashedMap extends AbstractMap implements Iterab */ protected static class KeySetIterator extends HashIterator implements Iterator { + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ @SuppressWarnings("unchecked") protected KeySetIterator(final AbstractHashedMap parent) { super((AbstractHashedMap) parent); @@ -418,9 +447,15 @@ public class AbstractHashedMap extends AbstractMap implements Iterab * @param the type of elements maintained by this collection */ protected static class Values extends AbstractCollection { + /** The parent map */ private final AbstractHashedMap parent; + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ protected Values(final AbstractHashedMap parent) { this.parent = parent; } @@ -453,6 +488,11 @@ public class AbstractHashedMap extends AbstractMap implements Iterab */ protected static class ValuesIterator extends HashIterator implements Iterator { + /** + * Constructs a new instance. + * + * @param parent The parent AbstractHashedMap. + */ @SuppressWarnings("unchecked") protected ValuesIterator(final AbstractHashedMap parent) { super((AbstractHashedMap) 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 extends AbstractHashedMap } /** - * 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 extends AbstractMap 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 extends AbstractMap /** * 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 extends AbstractBitwiseTrie 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 extends AbstractBitwiseTrie extends AbstractBitwiseTrie 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 keyAnalyzer, - final Map map) { + protected AbstractPatriciaTrie(final KeyAnalyzer keyAnalyzer, final Map 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 implements Comparator, 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 implements Trie, Serializable, Unmodif return new UnmodifiableTrie<>(trie); } + /** + * The delegate Trie. + */ private final Trie delegate; /**