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
The following commit(s) were added to refs/heads/master by this push:
new 0d48908 Javadoc: Close tags.
0d48908 is described below
commit 0d489086a3eee8f2194e0fedafe3dff7f9743497
Author: Gary Gregory <[email protected]>
AuthorDate: Wed May 8 20:41:28 2019 -0400
Javadoc: Close tags.
---
.../java/org/apache/commons/collections4/Bag.java | 19 +++++++++++++++++--
.../org/apache/commons/collections4/BagUtils.java | 8 ++++++++
.../java/org/apache/commons/collections4/BidiMap.java | 10 ++++++++++
.../apache/commons/collections4/ComparatorUtils.java | 6 ++++++
4 files changed, 41 insertions(+), 2 deletions(-)
diff --git a/src/main/java/org/apache/commons/collections4/Bag.java
b/src/main/java/org/apache/commons/collections4/Bag.java
index c6d9781..91e38cb 100644
--- a/src/main/java/org/apache/commons/collections4/Bag.java
+++ b/src/main/java/org/apache/commons/collections4/Bag.java
@@ -27,12 +27,14 @@ import java.util.Set;
* Suppose you have a Bag that contains <code>{a, a, b, c}</code>.
* Calling {@link #getCount(Object)} on <code>a</code> would return 2, while
* calling {@link #uniqueSet()} would return <code>{a, b, c}</code>.
+ * </p>
* <p>
* <i>NOTE: This interface violates the {@link Collection} contract.</i>
* The behavior specified in many of these methods is <i>not</i> the same
* as the behavior specified by <code>Collection</code>.
* The noncompliant methods are clearly marked with "(Violation)".
* Exercise caution when using a bag as a <code>Collection</code>.
+ * </p>
* <p>
* This violation resulted from the original specification of this interface.
* In an ideal world, the interface would be changed to fix the problems,
however
@@ -60,11 +62,13 @@ public interface Bag<E> extends Collection<E> {
* If the object is already in the {@link #uniqueSet()} then increment its
* count as reported by {@link #getCount(Object)}. Otherwise add it to the
* {@link #uniqueSet()} and report its count as 1.
+ * </p>
* <p>
* Since this method always increases the size of the bag,
* according to the {@link Collection#add(Object)} contract, it
* should always return <code>true</code>. Since it sometimes returns
* <code>false</code>, this method violates the contract.
+ * </p>
*
* @param object the object to add
* @return <code>true</code> if the object was not already in the
<code>uniqueSet</code>
@@ -78,6 +82,7 @@ public interface Bag<E> extends Collection<E> {
* If the object is already in the {@link #uniqueSet()} then increment its
* count as reported by {@link #getCount(Object)}. Otherwise add it to the
* {@link #uniqueSet()} and report its count as <code>nCopies</code>.
+ * </p>
*
* @param object the object to add
* @param nCopies the number of copies to add
@@ -90,10 +95,12 @@ public interface Bag<E> extends Collection<E> {
* Removes all occurrences of the given object from the bag.
* <p>
* This will also remove the object from the {@link #uniqueSet()}.
+ * </p>
* <p>
* According to the {@link Collection#remove(Object)} method,
* this method should only remove the <i>first</i> occurrence of the
* given object, not <i>all</i> occurrences.
+ * </p>
*
* @param object the object to remove
* @return <code>true</code> if this call changed the collection
@@ -106,6 +113,7 @@ public interface Bag<E> extends Collection<E> {
* <p>
* If the number of copies to remove is greater than the actual number of
* copies in the Bag, no error is thrown.
+ * </p>
*
* @param object the object to remove
* @param nCopies the number of copies to remove
@@ -117,6 +125,7 @@ public interface Bag<E> extends Collection<E> {
* Returns a {@link Set} of unique elements in the Bag.
* <p>
* Uniqueness constraints are the same as those in {@link java.util.Set}.
+ * </p>
*
* @return the Set of unique Bag elements
*/
@@ -137,11 +146,13 @@ public interface Bag<E> extends Collection<E> {
* given collection <code>coll</code> contains <code>n</code> copies
* of a given object, calling {@link #getCount(Object)} on that object must
* be <code>>= n</code> for all <code>n</code> in <code>coll</code>.
+ *
* <p>
* The {@link Collection#containsAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* return true if the bag contains at least one of every object contained
* in the given collection.
+ * </p>
*
* @param coll the collection to check against
* @return <code>true</code> if the Bag contains all the collection
@@ -157,10 +168,12 @@ public interface Bag<E> extends Collection<E> {
* the bag will have <code>n</code> fewer copies, assuming the bag
* had at least <code>n</code> copies to begin with.
*
- * <p>The {@link Collection#removeAll(Collection)} method specifies
+ * <p>
+ * The {@link Collection#removeAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* remove <i>all</i> occurrences of every object contained in the
* given collection.
+ * </p>
*
* @param coll the collection to remove
* @return <code>true</code> if this call changed the collection
@@ -179,10 +192,12 @@ public interface Bag<E> extends Collection<E> {
* <code>!coll.contains(e)</code>, then remove <code>e</code> and any
* of its copies.
*
- * <p>The {@link Collection#retainAll(Collection)} method specifies
+ * <p>
+ * The {@link Collection#retainAll(Collection)} method specifies
* that cardinality should <i>not</i> be respected; this method should
* keep <i>all</i> occurrences of every object contained in the
* given collection.
+ * </p>
*
* @param coll the collection to retain
* @return <code>true</code> if this call changed the collection
diff --git a/src/main/java/org/apache/commons/collections4/BagUtils.java
b/src/main/java/org/apache/commons/collections4/BagUtils.java
index c9bfed7..931a218 100644
--- a/src/main/java/org/apache/commons/collections4/BagUtils.java
+++ b/src/main/java/org/apache/commons/collections4/BagUtils.java
@@ -61,6 +61,7 @@ public class BagUtils {
* <p>
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
+ * </p>
*
* <pre>
* Bag bag = BagUtils.synchronizedBag(new HashBag());
@@ -105,6 +106,7 @@ public class BagUtils {
* IllegalArgumentException. It is important not to use the original bag
* after invoking this method, as it is a backdoor for adding invalid
* objects.
+ * </p>
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null
@@ -122,9 +124,11 @@ public class BagUtils {
* Each object is passed through the transformer as it is added to the Bag.
* It is important not to use the original bag after invoking this method,
* as it is a backdoor for adding untransformed objects.
+ * </p>
* <p>
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see {@link
TransformedBag#transformedBag(Bag, Transformer)}.
+ * </p>
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null
@@ -157,6 +161,7 @@ public class BagUtils {
* <p>
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
+ * </p>
*
* <pre>
* SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
@@ -203,6 +208,7 @@ public class BagUtils {
* IllegalArgumentException. It is important not to use the original bag
* after invoking this method, as it is a backdoor for adding invalid
* objects.
+ * </p>
*
* @param <E> the element type
* @param bag the sorted bag to predicate, must not be null
@@ -221,10 +227,12 @@ public class BagUtils {
* Each object is passed through the transformer as it is added to the Bag.
* It is important not to use the original bag after invoking this method,
* as it is a backdoor for adding untransformed objects.
+ * </p>
* <p>
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see
* {@link TransformedSortedBag#transformedSortedBag(SortedBag,
Transformer)}.
+ * </p>
*
* @param <E> the element type
* @param bag the bag to predicate, must not be null
diff --git a/src/main/java/org/apache/commons/collections4/BidiMap.java
b/src/main/java/org/apache/commons/collections4/BidiMap.java
index 0640943..b5a2e98 100644
--- a/src/main/java/org/apache/commons/collections4/BidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/BidiMap.java
@@ -26,14 +26,17 @@ import java.util.Set;
* This interface extends <code>Map</code> and so may be used anywhere a map
* is required. The interface provides an inverse map view, enabling
* full access to both directions of the <code>BidiMap</code>.
+ * </p>
* <p>
* Implementations should allow a value to be looked up from a key and
* a key to be looked up from a value with equal performance.
+ * </p>
* <p>
* This map enforces the restriction that there is a 1:1 relation between
* keys and values, meaning that multiple keys cannot map to the same value.
* This is required so that "inverting" the map results in a map without
* duplicate keys. See the {@link #put} method description for more
information.
+ * </p>
*
* @param <K> the type of the keys in the map
* @param <V> the type of the values in the map
@@ -48,6 +51,7 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* When adding a key-value pair, the value may already exist in the map
* against a different key. That mapping is removed, to ensure that the
* value only occurs once in the inverse map.
+ * </p>
* <pre>
* BidiMap map1 = new DualHashBidiMap();
* map.put("A","B"); // contains A mapped to B, as per Map
@@ -76,10 +80,12 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
/**
* Gets the key that is currently mapped to the specified value.
* <p>
+ * </p>
* If the value is not contained in the map, <code>null</code> is returned.
* <p>
* Implementations should seek to make this method perform equally as well
* as <code>get(Object)</code>.
+ * </p>
*
* @param value the value to find the key for
* @return the mapped key, or <code>null</code> if not found
@@ -96,9 +102,11 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* value (optional operation).
* <p>
* If the value is not contained in the map, <code>null</code> is returned.
+ * </p>
* <p>
* Implementations should seek to make this method perform equally as well
* as <code>remove(Object)</code>.
+ * </p>
*
* @param value the value to find the key-value pair for
* @return the key that was removed, <code>null</code> if nothing removed
@@ -117,10 +125,12 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* <p>
* Changes to one map will be visible in the other and vice versa.
* This enables both directions of the map to be accessed as a
<code>Map</code>.
+ * </p>
* <p>
* Implementations should seek to avoid creating a new object every time
this
* method is called. See <code>AbstractMap.values()</code> etc. Calling
this
* method on the inverse map should return the original.
+ * </p>
*
* @return an inverted bidirectional map
*/
diff --git a/src/main/java/org/apache/commons/collections4/ComparatorUtils.java
b/src/main/java/org/apache/commons/collections4/ComparatorUtils.java
index f030215..5c0f5f4 100644
--- a/src/main/java/org/apache/commons/collections4/ComparatorUtils.java
+++ b/src/main/java/org/apache/commons/collections4/ComparatorUtils.java
@@ -34,6 +34,7 @@ import
org.apache.commons.collections4.comparators.TransformingComparator;
* <code>comparators</code> package. This class merely provides a
* convenient central place if you have use for more than one class
* in the <code>comparators</code> subpackage.
+ * </p>
*
* @since 2.1
*/
@@ -119,8 +120,10 @@ public class ComparatorUtils {
* Gets a Comparator that can sort Boolean objects.
* <p>
* The parameter specifies whether true or false is sorted first.
+ * </p>
* <p>
* The comparator throws NullPointerException if a null value is compared.
+ * </p>
*
* @param trueFirst when <code>true</code>, sort
* <code>true</code> {@link Boolean}s before
@@ -137,6 +140,7 @@ public class ComparatorUtils {
* The returned comparator will consider a null value to be less than
* any nonnull value, and equal to any other null value. Two nonnull
* values will be evaluated with the given comparator.
+ * </p>
*
* @param <E> the object type to compare
* @param comparator the comparator that wants to allow nulls
@@ -157,6 +161,7 @@ public class ComparatorUtils {
* The returned comparator will consider a null value to be greater than
* any nonnull value, and equal to any other null value. Two nonnull
* values will be evaluated with the given comparator.
+ * </p>
*
* @param <E> the object type to compare
* @param comparator the comparator that wants to allow nulls
@@ -177,6 +182,7 @@ public class ComparatorUtils {
* Objects passed to the returned comparator will first be transformed
* by the given transformer before they are compared by the given
* comparator.
+ * </p>
*
* @param <I> the input object type of the transformed comparator
* @param <O> the object type of the decorated comparator
