Javadoc

- Close HTML tags
- Use longer lines
- Whitespace before tags
- Remove dead inline comments

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

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

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();

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.
      */

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
      */