You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2024/08/25 23:40:50 UTC
(commons-collections) 10/18: Javadoc
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 <ga...@gmail.com>
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;
/**