From c38b0eaba5ae1cf87ad014a089fa8bfb45565014 Mon Sep 17 00:00:00 2001 From: Doug Lea
A Queue implementation that extends this class must + *
A {@code Queue} implementation that extends this class must
* minimally define a method {@link Queue#offer} which does not permit
- * insertion of null elements, along with methods {@link
+ * insertion of {@code null} elements, along with methods {@link
* Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and
* {@link Collection#iterator}. Typically, additional methods will be
* overridden as well. If these requirements cannot be met, consider
@@ -59,7 +59,7 @@ package java.util;
*
* @since 1.5
* @author Doug Lea
- * @param This implementation returns true if offer succeeds,
- * else throws an IllegalStateException.
+ * This implementation returns {@code true} if {@code offer} succeeds,
+ * else throws an {@code IllegalStateException}.
*
* @param e the element to add
- * @return true (as specified by {@link Collection#add})
+ * @return {@code true} (as specified by {@link Collection#add})
* @throws IllegalStateException if the element cannot be added at this
* time due to capacity restrictions
* @throws ClassCastException if the class of the specified element
@@ -103,7 +103,7 @@ public abstract class AbstractQueue This implementation returns the result of poll
+ * This implementation returns the result of {@code poll}
* unless the queue is empty.
*
* @return the head of this queue
@@ -122,7 +122,7 @@ public abstract class AbstractQueue This implementation returns the result of peek
+ * This implementation returns the result of {@code peek}
* unless the queue is empty.
*
* @return the head of this queue
@@ -141,7 +141,7 @@ public abstract class AbstractQueue This implementation repeatedly invokes {@link #poll poll} until it
- * returns null.
+ * returns {@code null}.
*/
public void clear() {
while (poll() != null)
@@ -151,7 +151,7 @@ public abstract class AbstractQueue Most {@code ArrayDeque} operations run in amortized constant time.
- * Exceptions include {@link #remove(Object) remove}, {@link
- * #removeFirstOccurrence removeFirstOccurrence}, {@link #removeLastOccurrence
- * removeLastOccurrence}, {@link #contains contains}, {@link #iterator
- * iterator.remove()}, and the bulk operations, all of which run in linear
- * time.
+ * Exceptions include
+ * {@link #remove(Object) remove},
+ * {@link #removeFirstOccurrence removeFirstOccurrence},
+ * {@link #removeLastOccurrence removeLastOccurrence},
+ * {@link #contains contains},
+ * {@link #iterator iterator.remove()},
+ * and the bulk operations, all of which run in linear time.
*
- * The iterators returned by this class's {@code iterator} method are
- * fail-fast: If the deque is modified at any time after the iterator
- * is created, in any way except through the iterator's own {@code remove}
- * method, the iterator will generally throw a {@link
+ * The iterators returned by this class's {@link #iterator() iterator}
+ * method are fail-fast: If the deque is modified at any time after
+ * the iterator is created, in any way except through the iterator's own
+ * {@code remove} method, the iterator will generally throw a {@link
* ConcurrentModificationException}. Thus, in the face of concurrent
* modification, the iterator fails quickly and cleanly, rather than risking
* arbitrary, non-deterministic behavior at an undetermined time in the
@@ -80,7 +82,7 @@ import java.util.function.Consumer;
*
* @author Josh Bloch and Doug Lea
* @since 1.6
- * @param A {@code NavigableMap} may be accessed and traversed in either
- * ascending or descending key order. The {@code descendingMap}
+ * ascending or descending key order. The {@link #descendingMap}
* method returns a view of the map with the senses of all relational
* and directional methods inverted. The performance of ascending
* operations and views is likely to be faster than that of descending
- * ones. Methods {@code subMap}, {@code headMap},
- * and {@code tailMap} differ from the like-named {@code
- * SortedMap} methods in accepting additional arguments describing
- * whether lower and upper bounds are inclusive versus exclusive.
- * Submaps of any {@code NavigableMap} must implement the {@code
- * NavigableMap} interface.
+ * ones. Methods
+ * {@link #subMap(Object, boolean, Object, boolean) subMap(K, boolean, K, boolean)},
+ * {@link #headMap(Object, boolean) headMap(K, boolean)}, and
+ * {@link #tailMap(Object, boolean) tailMap(K, boolean)}
+ * differ from the like-named {@code SortedMap} methods in accepting
+ * additional arguments describing whether lower and upper bounds are
+ * inclusive versus exclusive. Submaps of any {@code NavigableMap}
+ * must implement the {@code NavigableMap} interface.
*
- * This interface additionally defines methods {@code firstEntry},
- * {@code pollFirstEntry}, {@code lastEntry}, and
- * {@code pollLastEntry} that return and/or remove the least and
+ * This interface additionally defines methods {@link #firstEntry},
+ * {@link #pollFirstEntry}, {@link #lastEntry}, and
+ * {@link #pollLastEntry} that return and/or remove the least and
* greatest mappings, if any exist, else returning {@code null}.
*
* Implementations of entry-returning methods are expected to
@@ -80,7 +82,7 @@ package java.util;
* implement {@code NavigableMap}, but extensions and implementations
* of this interface are encouraged to override these methods to return
* {@code NavigableMap}. Similarly,
- * {@link #keySet()} can be overriden to return {@code NavigableSet}.
+ * {@link #keySet()} can be overridden to return {@link NavigableSet}.
*
* This interface is a member of the
*
@@ -254,7 +256,7 @@ public interface NavigableMap The returned map has an ordering equivalent to
- * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator()).
+ * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
* The expression {@code m.descendingMap().descendingMap()} returns a
* view of {@code m} essentially equivalent to {@code m}.
*
diff --git a/jdk/src/java.base/share/classes/java/util/NavigableSet.java b/jdk/src/java.base/share/classes/java/util/NavigableSet.java
index 4dbb1c1cc45..40843905271 100644
--- a/jdk/src/java.base/share/classes/java/util/NavigableSet.java
+++ b/jdk/src/java.base/share/classes/java/util/NavigableSet.java
@@ -37,26 +37,30 @@ package java.util;
/**
* A {@link SortedSet} extended with navigation methods reporting
- * closest matches for given search targets. Methods {@code lower},
- * {@code floor}, {@code ceiling}, and {@code higher} return elements
+ * closest matches for given search targets. Methods {@link #lower},
+ * {@link #floor}, {@link #ceiling}, and {@link #higher} return elements
* respectively less than, less than or equal, greater than or equal,
* and greater than a given element, returning {@code null} if there
- * is no such element. A {@code NavigableSet} may be accessed and
- * traversed in either ascending or descending order. The {@code
- * descendingSet} method returns a view of the set with the senses of
- * all relational and directional methods inverted. The performance of
- * ascending operations and views is likely to be faster than that of
- * descending ones. This interface additionally defines methods
- * {@code pollFirst} and {@code pollLast} that return and remove the
- * lowest and highest element, if one exists, else returning {@code
- * null}. Methods {@code subSet}, {@code headSet},
- * and {@code tailSet} differ from the like-named {@code
- * SortedSet} methods in accepting additional arguments describing
- * whether lower and upper bounds are inclusive versus exclusive.
- * Subsets of any {@code NavigableSet} must implement the {@code
- * NavigableSet} interface.
+ * is no such element.
*
- * The return values of navigation methods may be ambiguous in
+ * A {@code NavigableSet} may be accessed and traversed in either
+ * ascending or descending order. The {@link #descendingSet} method
+ * returns a view of the set with the senses of all relational and
+ * directional methods inverted. The performance of ascending
+ * operations and views is likely to be faster than that of descending
+ * ones. This interface additionally defines methods {@link
+ * #pollFirst} and {@link #pollLast} that return and remove the lowest
+ * and highest element, if one exists, else returning {@code null}.
+ * Methods
+ * {@link #subSet(Object, boolean, Object, boolean) subSet(E, boolean, E, boolean)},
+ * {@link #headSet(Object, boolean) headSet(E, boolean)}, and
+ * {@link #tailSet(Object, boolean) tailSet(E, boolean)}
+ * differ from the like-named {@code SortedSet} methods in accepting
+ * additional arguments describing whether lower and upper bounds are
+ * inclusive versus exclusive. Subsets of any {@code NavigableSet}
+ * must implement the {@code NavigableSet} interface.
+ *
+ * The return values of navigation methods may be ambiguous in
* implementations that permit {@code null} elements. However, even
* in this case the result can be disambiguated by checking
* {@code contains(null)}. To avoid such issues, implementations of
@@ -172,7 +176,7 @@ public interface NavigableSet The returned set has an ordering equivalent to
- * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator()).
+ * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
* The expression {@code s.descendingSet().descendingSet()} returns a
* view of {@code s} essentially equivalent to {@code s}.
*
diff --git a/jdk/src/java.base/share/classes/java/util/PriorityQueue.java b/jdk/src/java.base/share/classes/java/util/PriorityQueue.java
index cc1af05aa36..7c929bda6d1 100644
--- a/jdk/src/java.base/share/classes/java/util/PriorityQueue.java
+++ b/jdk/src/java.base/share/classes/java/util/PriorityQueue.java
@@ -77,7 +77,7 @@ import java.util.function.Consumer;
*
* @since 1.5
* @author Josh Bloch, Doug Lea
- * @param Extension example. Here is a sketch of a class
* that customizes {@link ThreadPoolExecutor} to use
* a {@code CustomTask} class instead of the default {@code FutureTask}:
- * These bulk operations accept a {@code parallelismThreshold}
@@ -576,7 +572,7 @@ public class ConcurrentHashMap {@code String[] y = x.toArray(new String[0]);}
+ * {@code String[] y = x.toArray(new String[0]);}
*
* Note that {@code toArray(new Object[0])} is identical in function to
* {@code toArray()}.
@@ -820,13 +807,22 @@ public class ArrayDeque {@code String[] y = x.toArray(new String[0]);}
+ * {@code String[] y = x.toArray(new String[0]);}
*
* Note that {@code toArray(new Object[0])} is identical in function to
* {@code toArray()}.
@@ -489,7 +489,7 @@ public class PriorityQueue {@code
+ * {@code
* public class CustomThreadPoolExecutor extends ThreadPoolExecutor {
*
* static class CustomTask {@code String[] y = x.toArray(new String[0]);}
+ * {@code String[] y = x.toArray(new String[0]);}
*
* Note that {@code toArray(new Object[0])} is identical in function to
* {@code toArray()}.
@@ -614,53 +591,30 @@ public class ArrayBlockingQueue {@code
+ * {@code
* class Producer implements Runnable {
* private final BlockingQueue queue;
* Producer(BlockingQueue q) { queue = q; }
@@ -175,7 +175,7 @@ import java.util.Queue;
*
* @since 1.5
* @author Doug Lea
- * @param
- *
*
*
*
- *
- *