From 346c8e7e9e63f70a90cd4d17be567695a4826468 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@gmail.com>
Date: Sun, 20 Oct 2024 17:01:23 -0400
Subject: [PATCH] Javadoc

- Close HTML tags
- Use longer lines
- Whitespace before tags
- Remove dead inline comments
---
 .../collections4/map/AbstractHashedMap.java   | 23 +++++++++++
 .../collections4/map/AbstractLinkedMap.java   |  6 ++-
 .../map/AbstractReferenceMap.java             | 12 ++++++
 .../collections4/map/CompositeMap.java        |  1 +
 .../collections4/map/DefaultedMap.java        |  3 ++
 .../commons/collections4/map/Flat3Map.java    | 13 ++++++
 .../commons/collections4/map/LRUMap.java      | 13 +++++-
 .../commons/collections4/map/LinkedMap.java   |  2 +
 .../collections4/map/ListOrderedMap.java      | 12 +++++-
 .../commons/collections4/map/MultiKeyMap.java |  4 ++
 .../collections4/map/MultiValueMap.java       | 14 ++++++-
 .../collections4/map/PassiveExpiringMap.java  | 11 ++---
 .../collections4/map/PredicatedMap.java       |  1 +
 .../collections4/map/PredicatedSortedMap.java |  1 +
 .../map/ReferenceIdentityMap.java             |  4 ++
 .../collections4/map/SingletonMap.java        |  2 +
 .../collections4/map/StaticBucketMap.java     | 41 +++++++++----------
 .../collections4/map/TransformedMap.java      |  5 +++
 .../map/TransformedSortedMap.java             |  5 ++-
 .../multimap/AbstractListValuedMap.java       |  1 +
 .../multimap/AbstractSetValuedMap.java        |  1 +
 .../multimap/TransformedMultiValuedMap.java   |  5 +++
 .../multimap/UnmodifiableMultiValuedMap.java  |  1 +
 .../multiset/AbstractMapMultiSet.java         |  3 +-
 .../multiset/PredicatedMultiSet.java          |  1 +
 .../multiset/UnmodifiableMultiSet.java        |  1 +
 26 files changed, 152 insertions(+), 34 deletions(-)

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 a47fe87b71..96c7eb885b 100644
--- a/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
@@ -45,14 +45,17 @@
  * Key-value entries are stored in instances of the {@code HashEntry} class,
  * which can be overridden and replaced. The iterators can similarly be replaced,
  * without the need to replace the KeySet, EntrySet and Values view classes.
+ * </p>
  * <p>
  * Overridable methods are provided to change the default hashing behavior, and
  * to change how entries are added to and removed from the map. Hopefully, all you
  * need for unusual subclasses is here.
+ * </p>
  * <p>
  * NOTE: From Commons Collections 3.1 this class extends AbstractMap.
  * This is to provide backwards compatibility for ReferenceMap between v3.0 and v3.1.
  * This extends clause will be removed in v5.0.
+ * </p>
  *
  * @param <K> the type of the keys in this map
  * @param <V> the type of the values in this map
@@ -651,6 +654,7 @@ protected AbstractHashedMap(final Map<? extends K, ? extends V> map) {
      * <p>
      * This implementation adds the entry to the data storage table.
      * Subclasses could override to handle changes to the map.
+     * </p>
      *
      * @param entry  the entry to add
      * @param hashIndex  the index into the data array to store at
@@ -666,6 +670,7 @@ protected void addEntry(final HashEntry<K, V> entry, final int hashIndex) {
      * and {@code checkCapacity()}.
      * It also handles changes to {@code modCount} and {@code size}.
      * Subclasses could override to fully control adds to the map.
+     * </p>
      *
      * @param hashIndex  the index into the data array to store at
      * @param hashCode  the hash code of the key to add
@@ -718,6 +723,7 @@ protected int calculateThreshold(final int newCapacity, final float factor) {
      * Checks the capacity of the map and enlarges it if necessary.
      * <p>
      * This implementation uses the threshold to check if the map needs enlarging
+     * </p>
      */
     protected void checkCapacity() {
         if (size >= threshold) {
@@ -745,6 +751,7 @@ public void clear() {
      * <p>
      * To implement {@code clone()}, a subclass must implement the
      * {@code Cloneable} interface and make this method public.
+     * </p>
      *
      * @return a shallow clone
      * @throws InternalError if {@link AbstractMap#clone()} failed
@@ -827,6 +834,7 @@ public boolean containsValue(final Object value) {
      * <p>
      * The reverse conversion can be changed, if required, by overriding the
      * getKey() method in the hash entry.
+     * </p>
      *
      * @param key  the key convert
      * @return the converted key
@@ -841,6 +849,7 @@ protected Object convertKey(final Object key) {
      * This implementation creates a new HashEntry instance.
      * Subclasses can override this to return a different storage class,
      * or implement caching.
+     * </p>
      *
      * @param next  the next entry in sequence
      * @param hashCode  the hash code to use
@@ -896,6 +905,7 @@ protected Iterator<V> createValuesIterator() {
      * <p>
      * This implementation prepares the HashEntry for garbage collection.
      * Subclasses can override this to implement caching (override clear as well).
+     * </p>
      *
      * @param entry  the entry to destroy
      */
@@ -913,13 +923,16 @@ protected void destroyEntry(final HashEntry<K, V> entry) {
      * initialize the superclass before the subclass. Sometimes however, this isn't
      * what you want, as in this case the {@code put()} method on read can be
      * affected by subclass state.
+     * </p>
      * <p>
      * The solution adopted here is to deserialize the state data of this class in
      * this protected method. This method must be called by the
      * {@code readObject()} of the first serializable subclass.
+     * </p>
      * <p>
      * Subclasses may override if the subclass has a specific field that must be present
      * before {@code put()} or {@code calculateThreshold()} will work correctly.
+     * </p>
      *
      * @param in  the input stream
      * @throws IOException if an error occurs while reading from the stream
@@ -948,14 +961,17 @@ protected void doReadObject(final ObjectInputStream in) throws IOException, Clas
      * initialize the superclass before the subclass. Sometimes however, this isn't
      * what you want, as in this case the {@code put()} method on read can be
      * affected by subclass state.
+     * </p>
      * <p>
      * The solution adopted here is to serialize the state data of this class in
      * this protected method. This method must be called by the
      * {@code writeObject()} of the first serializable subclass.
+     * </p>
      * <p>
      * Subclasses may override if they have a specific field that must be present
      * on read before this implementation will work. Generally, the read determines
      * what must be serialized here, if anything.
+     * </p>
      *
      * @param out  the output stream
      * @throws IOException if an error occurs while writing to the stream
@@ -1137,6 +1153,7 @@ public V get(Object key) {
      * This method exists for subclasses that may need to perform a multi-step
      * process accessing the entry. The public methods in this class don't use this
      * method to gain a small performance boost.
+     * </p>
      *
      * @param key  the key
      * @return the entry, null if no match
@@ -1266,6 +1283,7 @@ public Set<K> keySet() {
      * methods to get the key and value, and set the value.
      * It avoids the need to create an entrySet/keySet/values object.
      * It also avoids creating the Map.Entry object.
+     * </p>
      *
      * @return the map iterator
      */
@@ -1308,6 +1326,7 @@ public V put(final K key, final V value) {
      * <p>
      * This implementation iterates around the specified map and
      * uses {@link #put(Object, Object)}.
+     * </p>
      *
      * @param map  the map to add
      * @throws NullPointerException if the map is null
@@ -1356,6 +1375,7 @@ public V remove(Object key) {
      * This implementation removes the entry from the data storage table.
      * The size is not updated.
      * Subclasses could override to handle changes to the map.
+     * </p>
      *
      * @param entry  the entry to remove
      * @param hashIndex  the index into the data structure
@@ -1375,6 +1395,7 @@ protected void removeEntry(final HashEntry<K, V> entry, final int hashIndex, fin
      * This implementation calls {@code removeEntry()} and {@code destroyEntry()}.
      * It also handles changes to {@code modCount} and {@code size}.
      * Subclasses could override to fully control removals from the map.
+     * </p>
      *
      * @param entry  the entry to remove
      * @param hashIndex  the index into the data structure
@@ -1392,6 +1413,7 @@ protected void removeMapping(final HashEntry<K, V> entry, final int hashIndex, f
      * <p>
      * This implementation sets all the data fields on the entry.
      * Subclasses could populate additional entry fields.
+     * </p>
      *
      * @param entry  the entry to update, not null
      * @param hashIndex  the index in the data array
@@ -1454,6 +1476,7 @@ public String toString() {
      * <p>
      * This implementation calls {@code setValue()} on the entry.
      * Subclasses could override to handle changes to the map.
+     * </p>
      *
      * @param entry  the entry to update
      * @param newValue  the new value to store
diff --git a/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java b/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
index e4b81ec865..e350f3e791 100644
--- a/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
@@ -426,6 +426,7 @@ protected AbstractLinkedMap(final Map<? extends K, ? extends V> map) {
      * <p>
      * This implementation adds the entry to the data storage table and
      * to the end of the linked list.
+     * </p>
      *
      * @param entry  the entry to add
      * @param hashIndex  the index into the data array to store at
@@ -480,6 +481,7 @@ public boolean containsValue(final Object value) {
      * Creates an entry to store the data.
      * <p>
      * This implementation creates a new LinkEntry instance.
+     * </p>
      *
      * @param next  the next entry in sequence
      * @param hashCode  the hash code to use
@@ -612,9 +614,10 @@ protected LinkEntry<K, V> getEntry(final Object key) {
     /**
      * Initialize this subclass during construction.
      * <p>
-     * NOTE: As from v3.2 this method calls
+     * Note: As from v3.2 this method calls
      * {@link #createEntry(HashEntry, int, Object, Object)} to create
      * the map entry object.
+     * </p>
      */
     @Override
     protected void init() {
@@ -675,6 +678,7 @@ public K previousKey(final Object key) {
      * <p>
      * This implementation removes the entry from the linked list chain, then
      * calls the superclass implementation.
+     * </p>
      *
      * @param entry  the entry to remove
      * @param hashIndex  the index into the data structure
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 86b4bfbcaa..4e5e3fac6c 100644
--- a/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
@@ -221,6 +221,7 @@ public ReferenceEntry(final AbstractReferenceMap<K, V> parent, final HashEntry<K
          * <p>
          * This implementation uses {@code isEqualKey} and
          * {@code isEqualValue} on the main map for comparison.
+         * </p>
          *
          * @param obj  the other map entry to compare to
          * @return true if equal, false if not
@@ -797,13 +798,16 @@ protected Iterator<V> createValuesIterator() {
      * initialize the superclass before the subclass. Sometimes however, this isn't
      * what you want, as in this case the {@code put()} method on read can be
      * affected by subclass state.
+     * </p>
      * <p>
      * The solution adopted here is to deserialize the state data of this class in
      * this protected method. This method must be called by the
      * {@code readObject()} of the first serializable subclass.
+     * </p>
      * <p>
      * Subclasses may override if the subclass has a specific field that must be present
      * before {@code put()} or {@code calculateThreshold()} will work correctly.
+     * </p>
      *
      * @param in  the input stream
      * @throws IOException if an error occurs while reading from the stream
@@ -846,14 +850,17 @@ protected void doReadObject(final ObjectInputStream in) throws IOException, Clas
      * initialize the superclass before the subclass. Sometimes however, this isn't
      * what you want, as in this case the {@code put()} method on read can be
      * affected by subclass state.
+     * </p>
      * <p>
      * The solution adopted here is to serialize the state data of this class in
      * this protected method. This method must be called by the
      * {@code writeObject()} of the first serializable subclass.
+     * </p>
      * <p>
      * Subclasses may override if they have a specific field that must be present
      * on read before this implementation will work. Generally, the read determines
      * what must be serialized here, if anything.
+     * </p>
      *
      * @param out  the output stream
      * @throws IOException if an error occurs while writing to the stream
@@ -955,6 +962,7 @@ public boolean isEmpty() {
      * <p>
      * This implementation converts the key from the entry to a real reference
      * before comparison.
+     * </p>
      *
      * @param key1  the first key to compare passed in from outside
      * @param key2  the second key extracted from the entry via {@code entry.key}
@@ -969,6 +977,7 @@ protected boolean isEqualKey(final Object key1, Object key2) {
 
     /**
      * Provided protected read-only access to the key type.
+     *
      * @param type the type to check against.
      * @return true if keyType has the specified type
      */
@@ -978,6 +987,7 @@ protected boolean isKeyType(final ReferenceStrength type) {
 
     /**
      * Provided protected read-only access to the value type.
+     *
      * @param type the type to check against.
      * @return true if valueType has the specified type
      */
@@ -1016,6 +1026,7 @@ public MapIterator<K, V> mapIterator() {
      * care must be taken if, for instance, you want stale
      * mappings to be removed on a periodic basis by some
      * background thread.
+     * </p>
      */
     protected void purge() {
         Reference<?> ref = queue.poll();
@@ -1073,6 +1084,7 @@ protected void purgeBeforeRead() {
      * Purges stale mappings from this map before write operations.
      * <p>
      * This implementation calls {@link #purge()} to maintain a consistent state.
+     * </p>
      */
     protected void purgeBeforeWrite() {
         purge();
diff --git a/src/main/java/org/apache/commons/collections4/map/CompositeMap.java b/src/main/java/org/apache/commons/collections4/map/CompositeMap.java
index 7f3a806f62..d6ee47cf41 100644
--- a/src/main/java/org/apache/commons/collections4/map/CompositeMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/CompositeMap.java
@@ -387,6 +387,7 @@ public boolean isEmpty() {
      * <p>
      * This implementation returns a {@code CompositeSet} which
      * composites the key sets from all of the composited maps.
+     * </p>
      *
      * @return a set view of the keys contained in this map.
      */
diff --git a/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java b/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
index 86fe2fa9ce..8803029bde 100644
--- a/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
@@ -99,6 +99,7 @@ public static <K, V> DefaultedMap<K, V> defaultedMap(final Map<K, V> map, final
      * The transformer specified is called when a missing key is found.
      * The key is passed to the transformer as the input, and the result
      * will be returned as the result of the map get(key) method.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
@@ -117,6 +118,7 @@ public static <K, V> Map<K, V> defaultedMap(final Map<K, V> map,
      * Factory method to create a defaulting map.
      * <p>
      * The value specified is returned when a missing key is found.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
@@ -160,6 +162,7 @@ public DefaultedMap(final Transformer<? super K, ? extends V> defaultValueTransf
      * <p>
      * The object passed in will be returned by the map whenever an
      * unknown key is requested.
+     * </p>
      *
      * @param defaultValue  the default value to return when the key is not found
      */
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 328fa5569c..0bfa253d6f 100644
--- a/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
+++ b/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
@@ -287,6 +287,7 @@ public String toString() {
         }
 
     }
+
     /**
      * FlatMapIterator
      */
@@ -392,10 +393,12 @@ public String toString() {
             return "Iterator[]";
         }
     }
+
     /**
      * KeySet
      */
     static class KeySet<K> extends AbstractSet<K> {
+
         private final Flat3Map<K, ?> parent;
 
         KeySet(final Flat3Map<K, ?> parent) {
@@ -435,6 +438,7 @@ public int size() {
             return parent.size();
         }
     }
+
     /**
      * KeySetIterator
      */
@@ -450,10 +454,12 @@ public K next() {
             return nextEntry().getKey();
         }
     }
+
     /**
      * Values
      */
     static class Values<V> extends AbstractCollection<V> {
+
         private final Flat3Map<?, V> parent;
 
         Values(final Flat3Map<?, V> parent) {
@@ -486,6 +492,7 @@ public int size() {
             return parent.size();
         }
     }
+
     /**
      * ValuesIterator
      */
@@ -501,10 +508,13 @@ public V next() {
             return nextEntry().getValue();
         }
     }
+
     /** Serialization version */
     private static final long serialVersionUID = -6701087419741928296L;
+
     /** The size of the map, used while in flat mode */
     private transient int size;
+
     /** Hash, used while in flat mode */
     private transient int hash1;
 
@@ -709,6 +719,7 @@ private void convertToMap() {
      * This can be overridden by subclasses to provide a different map implementation.
      * Not every AbstractHashedMap is suitable, identity and reference based maps
      * would be poor choices.
+     * </p>
      *
      * @return a new AbstractHashedMap or subclass
      * @since 3.1
@@ -724,6 +735,7 @@ protected AbstractHashedMap<K, V> createDelegateMap() {
      * NOTE: from 4.0, the returned Map Entry will be an independent object and will
      * not change anymore as the iterator progresses. To avoid this additional object
      * creation and simply iterate through the entries, use {@link #mapIterator()}.
+     * </p>
      *
      * @return the entrySet view
      */
@@ -895,6 +907,7 @@ public Set<K> keySet() {
      * methods to get the key and value, and set the value.
      * It avoids the need to create an entrySet/keySet/values object.
      * It also avoids creating the Map Entry object.
+     * </p>
      *
      * @return the map iterator
      */
diff --git a/src/main/java/org/apache/commons/collections4/map/LRUMap.java b/src/main/java/org/apache/commons/collections4/map/LRUMap.java
index 9cd375a591..f2e9151f45 100644
--- a/src/main/java/org/apache/commons/collections4/map/LRUMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/LRUMap.java
@@ -193,6 +193,7 @@ public LRUMap(final int maxSize,
      * Constructor copying elements from another map.
      * <p>
      * The maximum size is set from the map's size.
+     * </p>
      *
      * @param map  the map to copy
      * @throws NullPointerException if the map is null
@@ -223,10 +224,12 @@ public LRUMap(final Map<? extends K, ? extends V> map, final boolean scanUntilRe
      * <p>
      * This implementation checks the LRU size and determines whether to
      * discard an entry or not using {@link #removeLRU(AbstractLinkedMap.LinkEntry)}.
+     * </p>
      * <p>
      * From Commons Collections 3.1 this method uses {@link #isFull()} rather
      * than accessing {@code size} and {@code maxSize} directly.
      * It also handles the scanUntilRemovable functionality.
+     * </p>
      *
      * @param hashIndex  the index into the data array to store at
      * @param hashCode  the hash code of the key to add
@@ -327,6 +330,7 @@ public V get(final Object key) {
      * If {@code updateToMRU} is {@code true}, the position of the key in the map
      * is changed to the most recently used position (last), otherwise the iteration
      * order is not changed by this operation.
+     * </p>
      *
      * @param key  the key
      * @param updateToMRU  whether the key shall be updated to the
@@ -380,6 +384,7 @@ public int maxSize() {
      * Moves an entry to the MRU position at the end of the list.
      * <p>
      * This implementation moves the updated entry to the end of the list.
+     * </p>
      *
      * @param entry  the entry to update
      */
@@ -421,6 +426,7 @@ private void readObject(final ObjectInputStream in) throws IOException, ClassNot
      * <p>
      * This method exists for subclasses to override. A subclass may wish to
      * provide cleanup of resources when an entry is removed. For example:
+     * </p>
      * <pre>
      * protected boolean removeLRU(LinkEntry entry) {
      *   releaseResources(entry.getValue());  // release resources held by entry
@@ -430,6 +436,7 @@ private void readObject(final ObjectInputStream in) throws IOException, ClassNot
      * <p>
      * Alternatively, a subclass may choose to not remove the entry or selectively
      * keep certain LRU entries. For example:
+     * </p>
      * <pre>
      * protected boolean removeLRU(LinkEntry entry) {
      *   if (entry.getKey().toString().startsWith("System.")) {
@@ -439,13 +446,16 @@ private void readObject(final ObjectInputStream in) throws IOException, ClassNot
      *   }
      * }
      * </pre>
+     * <p>
      * The effect of returning false is dependent on the scanUntilRemovable flag.
      * If the flag is true, the next LRU entry will be passed to this method and so on
      * until one returns false and is removed, or every entry in the map has been passed.
      * If the scanUntilRemovable flag is false, the map will exceed the maximum size.
+     * </p>
      * <p>
-     * NOTE: Commons Collections 3.0 passed the wrong entry to this method.
+     * Note: Commons Collections 3.0 passed the wrong entry to this method.
      * This is fixed in version 3.1 onwards.
+     * </p>
      *
      * @param entry  the entry to be removed
      * @return {@code true}
@@ -502,6 +512,7 @@ protected void reuseMapping(final LinkEntry<K, V> entry, final int hashIndex, fi
      * <p>
      * This implementation moves the updated entry to the end of the list
      * using {@link #moveToMRU(AbstractLinkedMap.LinkEntry)}.
+     * </p>
      *
      * @param entry  the entry to update
      * @param newValue  the new value to store
diff --git a/src/main/java/org/apache/commons/collections4/map/LinkedMap.java b/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
index 6bfc2a8484..0683720c35 100644
--- a/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
@@ -227,8 +227,10 @@ public LinkedMap(final Map<? extends K, ? extends V> map) {
      * the end of the list, which is an unexpected side effect of changing the
      * value of a list.  This occurs because changing the key, changes when the
      * mapping is added to the map and thus where it appears in the list.
+     * </p>
      * <p>
      * An alternative to this method is to use {@link #keySet()}.
+     * </p>
      *
      * @see #keySet()
      * @return The ordered list of keys.
diff --git a/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java b/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
index f08dcb1afe..b1d8558509 100644
--- a/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
@@ -380,6 +380,7 @@ public int size() {
      * Factory method to create an ordered map.
      * <p>
      * An {@code ArrayList} is used to retain order.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
@@ -425,9 +426,11 @@ protected ListOrderedMap(final Map<K, V> map) {
      * the end of the list, which is an unexpected side effect of changing the
      * value of a list.  This occurs because changing the key, changes when the
      * mapping is added to the map and thus where it appears in the list.
+     * </p>
      * <p>
      * An alternative to this method is to use the better named
      * {@link #keyList()} or {@link #keySet()}.
+     * </p>
      *
      * @see #keyList()
      * @see #keySet()
@@ -447,6 +450,7 @@ public void clear() {
      * Gets a view over the entries in the map.
      * <p>
      * The Set will be ordered by object insertion into the map.
+     * </p>
      *
      * @return the fully modifiable set view over the entries
      */
@@ -506,6 +510,7 @@ public int indexOf(final Object key) {
      * <p>
      * The List will be ordered by object insertion into the map.
      * The List is unmodifiable.
+     * </p>
      *
      * @see #keySet()
      * @return the unmodifiable list view over the keys
@@ -519,6 +524,7 @@ public List<K> keyList() {
      * Gets a view over the keys in the map.
      * <p>
      * The Collection will be ordered by object insertion into the map.
+     * </p>
      *
      * @see #keyList()
      * @return the fully modifiable collection view over the keys
@@ -542,7 +548,6 @@ public K lastKey() {
         return insertOrder.get(size() - 1);
     }
 
-    // Implement OrderedMap
     @Override
     public OrderedMapIterator<K, V> mapIterator() {
         return new ListOrderedMapIterator<>(this);
@@ -587,10 +592,12 @@ public K previousKey(final Object key) {
      * is removed and the new mapping added at the specified index.
      * The remove may change the effect of the index. The index is
      * always calculated relative to the original state of the map.
+     * </p>
      * <p>
      * Thus, the steps are: (1) remove the existing key-value mapping,
      * then (2) insert the new key-value mapping at the position it
      * would have been inserted had the remove not occurred.
+     * </p>
      *
      * @param index  the index at which the mapping should be inserted
      * @param key  the key
@@ -751,6 +758,7 @@ public String toString() {
      * <p>
      * The List will be ordered by object insertion into the map.
      * The List supports remove and set, but does not support add.
+     * </p>
      *
      * @see #values()
      * @return the partially modifiable list view over the values
@@ -764,9 +772,11 @@ public List<V> valueList() {
      * Gets a view over the values in the map.
      * <p>
      * The Collection will be ordered by object insertion into the map.
+     * </p>
      * <p>
      * From Commons Collections 3.2, this Collection can be cast
      * to a list, see {@link #valueList()}
+     * </p>
      *
      * @see #valueList()
      * @return the fully modifiable collection view over the values
diff --git a/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java b/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
index 76d3301811..6d9e6e9b72 100644
--- a/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
@@ -684,6 +684,7 @@ private void readObject(final ObjectInputStream in) throws IOException, ClassNot
      * <p>
      * This method removes all the mappings where the {@code MultiKey}
      * has one or more keys, and the first matches that specified.
+     * </p>
      *
      * @param key1  the first key
      * @return true if any elements were removed
@@ -707,6 +708,7 @@ public boolean removeAll(final Object key1) {
      * <p>
      * This method removes all the mappings where the {@code MultiKey}
      * has two or more keys, and the first two match those specified.
+     * </p>
      *
      * @param key1  the first key
      * @param key2  the second key
@@ -732,6 +734,7 @@ public boolean removeAll(final Object key1, final Object key2) {
      * <p>
      * This method removes all the mappings where the {@code MultiKey}
      * has three or more keys, and the first three match those specified.
+     * </p>
      *
      * @param key1  the first key
      * @param key2  the second key
@@ -759,6 +762,7 @@ public boolean removeAll(final Object key1, final Object key2, final Object key3
      * <p>
      * This method removes all the mappings where the {@code MultiKey}
      * has four or more keys, and the first four match those specified.
+     * </p>
      *
      * @param key1  the first key
      * @param key2  the second key
diff --git a/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java b/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java
index 566ebea21a..779d7a0263 100644
--- a/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java
@@ -273,6 +273,7 @@ public void clear() {
      * Checks whether the map contains the value specified.
      * <p>
      * This checks all collections against all keys for the value, and thus could be slow.
+     * </p>
      *
      * @param value  the value to search for
      * @return true if the map contains the value
@@ -312,6 +313,7 @@ public boolean containsValue(final Object key, final Object value) {
      * <p>
      * This method can be overridden to perform your own processing
      * instead of using the factory.
+     * </p>
      *
      * @param size  the collection size that is about to be added
      * @return the new collection
@@ -323,9 +325,10 @@ protected Collection<V> createCollection(final int size) {
     /**
      * {@inheritDoc}
      * <p>
-     * NOTE: the returned Entry objects will contain as value a {@link Collection}
+     * Note: the returned Entry objects will contain as value a {@link Collection}
      * of all values that are mapped to the given key. To get a "flattened" version
      * of all mappings contained in this map, use {@link #iterator()}.
+     * </p>
      *
      * @see #iterator()
      */
@@ -351,9 +354,11 @@ public Collection<V> getCollection(final Object key) {
      * <p>
      * The iterator will return multiple Entry objects with the same key
      * if there are multiple values mapped to this key.
+     * </p>
      * <p>
-     * NOTE: calling {@link java.util.Map.Entry#setValue(Object)} on any of the returned
+     * Note: calling {@link java.util.Map.Entry#setValue(Object)} on any of the returned
      * elements will result in a {@link UnsupportedOperationException}.
+     * </p>
      *
      * @return the iterator of all mappings in this map
      * @since 4.0
@@ -408,6 +413,7 @@ public Iterator<V> iterator(final Object key) {
      * <p>
      * Unlike a normal {@code Map} the previous value is not replaced.
      * Instead, the new value is added to the collection stored against the key.
+     * </p>
      *
      * @param key  the key to store against
      * @param value  the value to add to the collection at the key
@@ -468,6 +474,7 @@ public boolean putAll(final K key, final Collection<V> values) {
      * added using {@code put(Object,Object)}.
      * If you call this method with a multi map, each entry is
      * added using {@code putAll(Object,Collection)}.
+     * </p>
      *
      * @param map  the map to copy (either a normal or multi map)
      */
@@ -504,9 +511,11 @@ private void readObject(final ObjectInputStream in) throws IOException, ClassNot
      * <p>
      * The item is removed from the collection mapped to the specified key.
      * Other values attached to that key are unaffected.
+     * </p>
      * <p>
      * If the last value for a key is removed, {@code null} will be returned
      * from a subsequent {@code get(key)}.
+     * </p>
      *
      * @param key  the key to remove from
      * @param value the value to remove
@@ -559,6 +568,7 @@ public int totalSize() {
      * Gets a collection containing all the values in the map.
      * <p>
      * This returns a collection containing the combination of values from all keys.
+     * </p>
      *
      * @return a collection view of the values contained in this map
      */
diff --git a/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java b/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
index 414b9bba37..fb0b0b5dd0 100644
--- a/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
@@ -419,11 +419,12 @@ private long now() {
     }
 
     /**
-    * Add the given key-value pair to this map as well as recording the entry's expiration time based on
-    * the current time in milliseconds and this map's {@link #expiringPolicy}.
-    * <p>
-    * {@inheritDoc}
-    */
+     * {@inheritDoc}
+     * <p>
+     * Add the given key-value pair to this map as well as recording the entry's expiration time based on the current time in milliseconds and this map's
+     * {@link #expiringPolicy}.
+     * </p>
+     */
     @Override
     public V put(final K key, final V value) {
         // remove the previous record
diff --git a/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java b/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
index 7e7f6455d0..ae61ee8078 100644
--- a/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
@@ -63,6 +63,7 @@ public class PredicatedMap<K, V>
      * <p>
      * If there are any elements already in the list being decorated, they
      * are validated.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
diff --git a/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java b/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
index 840ad4c965..f1a0f2c935 100644
--- a/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
@@ -63,6 +63,7 @@ public class PredicatedSortedMap<K, V> extends PredicatedMap<K, V> implements So
      * <p>
      * If there are any elements already in the list being decorated, they
      * are validated.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
diff --git a/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java b/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
index 062ea23644..f56d04d2a1 100644
--- a/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
@@ -173,6 +173,7 @@ public ReferenceIdentityMap(final ReferenceStrength keyType, final ReferenceStre
      * Gets the hash code for the key specified.
      * <p>
      * This implementation uses the identity hash code.
+     * </p>
      *
      * @param key  the key to get a hash code for
      * @return the hash code
@@ -186,6 +187,7 @@ protected int hash(final Object key) {
      * Gets the hash code for a MapEntry.
      * <p>
      * This implementation uses the identity hash code.
+     * </p>
      *
      * @param key  the key to get a hash code for, may be null
      * @param value  the value to get a hash code for, may be null
@@ -202,6 +204,7 @@ protected int hashEntry(final Object key, final Object value) {
      * <p>
      * This implementation converts the key from the entry to a real reference
      * before comparison and uses {@code ==}.
+     * </p>
      *
      * @param key1  the first key to compare passed in from outside
      * @param key2  the second key extracted from the entry via {@code entry.key}
@@ -217,6 +220,7 @@ protected boolean isEqualKey(final Object key1, Object key2) {
      * Compares two values for equals.
      * <p>
      * This implementation uses {@code ==}.
+     * </p>
      *
      * @param value1  the first value to compare passed in from outside
      * @param value2  the second value extracted from the entry via {@code getValue()}
diff --git a/src/main/java/org/apache/commons/collections4/map/SingletonMap.java b/src/main/java/org/apache/commons/collections4/map/SingletonMap.java
index 4922cfd7bc..7dd8ef446e 100644
--- a/src/main/java/org/apache/commons/collections4/map/SingletonMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/SingletonMap.java
@@ -488,6 +488,7 @@ public K previousKey(final K key) {
      * <p>
      * An IllegalArgumentException is thrown if the key does not match as the map
      * is fixed size.
+     * </p>
      *
      * @param key  the key to set, must be the key of the map
      * @param value  the value to set
@@ -508,6 +509,7 @@ public V put(final K key, final V value) {
      * The map must be of size 0 or size 1.
      * If it is size 1, the key must match the key of this map otherwise an
      * IllegalArgumentException is thrown.
+     * </p>
      *
      * @param map  the map to add, must be size 0 or 1, and the key must match
      * @throws NullPointerException if the map is null
diff --git a/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java b/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
index 8611412802..a33af9c601 100644
--- a/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
@@ -383,21 +383,20 @@ public StaticBucketMap(final int numBuckets) {
     }
 
     /**
-     *  Prevents any operations from occurring on this map while the
-     *  given {@link Runnable} executes.  This method can be used, for
-     *  instance, to execute a bulk operation atomically:
-     *
-     *  <pre>
-     *    staticBucketMapInstance.atomic(new Runnable() {
-     *        public void run() {
-     *            staticBucketMapInstance.putAll(map);
-     *        }
-     *    });
-     *  </pre>
-     *
-     *  It can also be used if you need a reliable iterator:
+     * Prevents any operations from occurring on this map while the given {@link Runnable} executes. This method can be used, for instance, to execute a bulk
+     * operation atomically:
+     * <pre>
+     * staticBucketMapInstance.atomic(new Runnable() {
+     *     public void run() {
+     *         staticBucketMapInstance.putAll(map);
+     *     }
+     * });
+     * </pre>
+     * <p>
+     * It can also be used if you need a reliable iterator:
+     * </p>
      *
-     *  <pre>
+     * <pre>
      *    staticBucketMapInstance.atomic(new Runnable() {
      *        public void run() {
      *            Iterator iterator = staticBucketMapInstance.iterator();
@@ -406,15 +405,13 @@ public StaticBucketMap(final int numBuckets) {
      *            }
      *        }
      *    });
-     *  </pre>
-     *
-     *  <b>Implementation note:</b> This method requires a lot of time
-     *  and a ton of stack space.  Essentially a recursive algorithm is used
-     *  to enter each bucket's monitor.  If you have twenty thousand buckets
-     *  in your map, then the recursive method will be invoked twenty thousand
-     *  times.  You have been warned.
+     * </pre>
+     * <p>
+     * <b>Implementation note:</b> This method requires a lot of time and a ton of stack space. Essentially a recursive algorithm is used to enter each bucket's
+     * monitor. If you have twenty thousand buckets in your map, then the recursive method will be invoked twenty thousand times. You have been warned.
+     * </p>
      *
-     *  @param runnable  the code to execute atomically
+     * @param runnable the code to execute atomically
      */
     public void atomic(final Runnable runnable) {
         atomic(Objects.requireNonNull(runnable, "runnable"), 0);
diff --git a/src/main/java/org/apache/commons/collections4/map/TransformedMap.java b/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
index f7e1768f2d..ab6d28362c 100644
--- a/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
@@ -63,6 +63,7 @@ public class TransformedMap<K, V>
      * If there are any elements already in the map being decorated, they
      * will be transformed by this method.
      * Contrast this with {@link #transformingMap(Map, Transformer, Transformer)}.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
@@ -90,6 +91,7 @@ public static <K, V> TransformedMap<K, V> transformedMap(final Map<K, V> map,
      * If there are any elements already in the map being decorated, they
      * are NOT transformed.
      * Contrast this with {@link #transformedMap(Map, Transformer, Transformer)}.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
@@ -117,6 +119,7 @@ public static <K, V> TransformedMap<K, V> transformingMap(final Map<K, V> map,
      * <p>
      * If there are any elements already in the collection being decorated, they
      * are NOT transformed.
+     * </p>
      *
      * @param map  the map to decorate, must not be null
      * @param keyTransformer  the transformer to use for key conversion, null means no conversion
@@ -199,6 +202,7 @@ protected K transformKey(final K object) {
      * Transforms a map.
      * <p>
      * The transformer itself may throw an exception if necessary.
+     * </p>
      *
      * @param map  the map to transform
      * @return the transformed object
@@ -220,6 +224,7 @@ protected Map<K, V> transformMap(final Map<? extends K, ? extends V> map) {
      * Transforms a value.
      * <p>
      * The transformer itself may throw an exception if necessary.
+     * </p>
      *
      * @param object  the object to transform
      * @return the transformed object
diff --git a/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java b/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
index 982b36fd8b..fb5bdc8916 100644
--- a/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
@@ -59,6 +59,7 @@ public class TransformedSortedMap<K, V>
      * If there are any elements already in the map being decorated, they
      * will be transformed by this method.
      * Contrast this with {@link #transformingSortedMap(SortedMap, Transformer, Transformer)}.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
@@ -88,6 +89,7 @@ public static <K, V> TransformedSortedMap<K, V> transformedSortedMap(final Sorte
      * <p>
      * If there are any elements already in the map being decorated, they are NOT transformed.
      * Contrast this with {@link #transformedSortedMap(SortedMap, Transformer, Transformer)}.
+     * </p>
      *
      * @param <K>  the key type
      * @param <V>  the value type
@@ -108,7 +110,8 @@ public static <K, V> TransformedSortedMap<K, V> transformingSortedMap(final Sort
      * Constructor that wraps (not copies).
      * <p>
      * If there are any elements already in the collection being decorated, they
-     * are NOT transformed.</p>
+     * are NOT transformed.
+     * </p>
      *
      * @param map  the map to decorate, must not be null
      * @param keyTransformer  the predicate to validate the keys, null means no transformation
diff --git a/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java b/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
index bae2865268..52e144a35f 100644
--- a/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
@@ -269,6 +269,7 @@ protected Map<K, List<V>> getMap() {
      * Removes all values associated with the specified key.
      * <p>
      * A subsequent {@code get(Object)} would return an empty list.
+     * </p>
      *
      * @param key  the key to remove values from
      * @return the {@code List} of values removed, will return an empty,
diff --git a/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java b/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
index 6f11527f04..7f563bcdbd 100644
--- a/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
@@ -115,6 +115,7 @@ protected Map<K, Set<V>> getMap() {
      * Removes all values associated with the specified key.
      * <p>
      * A subsequent {@code get(Object)} would return an empty set.
+     * </p>
      *
      * @param key the key to remove values from
      * @return the {@code Set} of values removed, will return an empty,
diff --git a/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java b/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
index 03174edaeb..6094a46ddb 100644
--- a/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
@@ -53,6 +53,7 @@ public class TransformedMultiValuedMap<K, V> extends AbstractMultiValuedMapDecor
      * If there are any elements already in the map being decorated, they will
      * be transformed by this method. Contrast this with
      * {@link #transformingMap(MultiValuedMap, Transformer, Transformer)}.
+     * </p>
      *
      * @param <K> the key type
      * @param <V> the value type
@@ -81,6 +82,7 @@ public static <K, V> TransformedMultiValuedMap<K, V> transformedMap(final MultiV
      * If there are any elements already in the map being decorated, they are
      * NOT transformed. Contrast this with
      * {@link #transformedMap(MultiValuedMap, Transformer, Transformer)}.
+     * </p>
      *
      * @param <K> the key type
      * @param <V> the value type
@@ -107,6 +109,7 @@ public static <K, V> TransformedMultiValuedMap<K, V> transformingMap(final Multi
      * <p>
      * If there are any elements already in the collection being decorated, they
      * are NOT transformed.
+     * </p>
      *
      * @param map  the MultiValuedMap to decorate, may not be null
      * @param keyTransformer  the transformer to use for key conversion, null means no conversion
@@ -159,6 +162,7 @@ public boolean putAll(final MultiValuedMap<? extends K, ? extends V> map) {
      * Transforms a key.
      * <p>
      * The transformer itself may throw an exception if necessary.
+     * </p>
      *
      * @param object  the object to transform
      * @return the transformed object
@@ -174,6 +178,7 @@ protected K transformKey(final K object) {
      * Transforms a value.
      * <p>
      * The transformer itself may throw an exception if necessary.
+     * </p>
      *
      * @param object  the object to transform
      * @return the transformed object
diff --git a/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java b/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
index 4f9d9838fd..537beea173 100644
--- a/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
@@ -52,6 +52,7 @@ public final class UnmodifiableMultiValuedMap<K, V>
      * Factory method to create an unmodifiable MultiValuedMap.
      * <p>
      * If the map passed in is already unmodifiable, it is returned.
+     * </p>
      *
      * @param <K> the type of key elements
      * @param <V> the type of value elements
diff --git a/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java b/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
index dfdfaedbd0..815172756f 100644
--- a/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
@@ -484,7 +484,8 @@ public int remove(final Object object, final int occurrences) {
     /**
      * Sets the map being wrapped.
      * <p>
-     * <b>NOTE:</b> this method should only be used during deserialization
+     * <b>Note:</b> this method should only be used during deserialization
+     * </p>
      *
      * @param map the map to wrap
      */
diff --git a/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java b/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
index 3f2f4504cc..89e7a657ad 100644
--- a/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
@@ -71,6 +71,7 @@ public static <E> PredicatedMultiSet<E> predicatedMultiSet(final MultiSet<E> mul
      * <p>
      * If there are any elements already in the multiset being decorated, they
      * are validated.
+     * </p>
      *
      * @param multiset  the multiset to decorate, must not be null
      * @param predicate  the predicate to use for validation, must not be null
diff --git a/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java b/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
index e593a0a1c2..919c6ff651 100644
--- a/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
@@ -48,6 +48,7 @@ public final class UnmodifiableMultiSet<E>
      * Factory method to create an unmodifiable multiset.
      * <p>
      * If the multiset passed in is already unmodifiable, it is returned.
+     * </p>
      *
      * @param <E>  the type of the elements in the multiset
      * @param multiset  the multiset to decorate, may not be null