464727 - Update Javadoc for Java 8 DocLint

+ Fixed jetty-util's javadoc

jetty-util/src/main/java/org/eclipse/jetty/util/AbstractTrie.java

@@ -22,12 +22,13 @@
 import java.nio.charset.StandardCharsets;
 
 
-/* ------------------------------------------------------------ */
-/** Abstract Trie implementation.
+/** 
+ * Abstract Trie implementation.
  * <p>Provides some common implementations, which may not be the most
  * efficient. For byte operations, the assumption is made that the charset
  * is ISO-8859-1</p>
- * @param <V>
+ * 
+ * @param <V> the type of object that the Trie holds
  */
 public abstract class AbstractTrie<V> implements Trie<V>
 {

jetty-util/src/main/java/org/eclipse/jetty/util/ArrayQueue.java

@@ -25,11 +25,12 @@
 /* ------------------------------------------------------------ */
 /**
  * Queue backed by circular array.
- * <p/>
+ * <p>
  * This partial Queue implementation (also with {@link #remove()} for stack operation)
  * is backed by a growable circular array.
+ * </p>
  *
- * @param <E>
+ * @param <E> the type of object the queue holds
  */
 public class ArrayQueue<E> extends AbstractList<E> implements Queue<E>
 {

jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java

@@ -24,20 +24,22 @@
 import java.util.Set;
 
 
-/* ------------------------------------------------------------ */
 /** 
  * <p>A Ternary Trie String lookup data structure.</p>
+ * <p>
  * This Trie is of a fixed size and cannot grow (which can be a good thing with regards to DOS when used as a cache).
+ * </p>
  * <p>
- * The Trie is stored in 3 arrays:<dl>
+ * The Trie is stored in 3 arrays:
+ * </p>
+ * <dl>
  * <dt>char[] _tree</dt><dd>This is semantically 2 dimensional array flattened into a 1 dimensional char array. The second dimension
  * is that every 4 sequential elements represents a row of: character; hi index; eq index; low index, used to build a
  * ternary trie of key strings.</dd>
- * <dt>String[] _key<dt><dd>An array of key values where each element matches a row in the _tree array. A non zero key element 
+ * <dt>String[] _key</dt><dd>An array of key values where each element matches a row in the _tree array. A non zero key element 
  * indicates that the _tree row is a complete key rather than an intermediate character of a longer key.</dd>
  * <dt>V[] _value</dt><dd>An array of values corresponding to the _key array</dd>
  * </dl>
- * </p>
  * <p>The lookup of a value will iterate through the _tree array matching characters. If the equal tree branch is followed,
  * then the _key array is looked up to see if this is a complete match.  If a match is found then the _value array is looked up
  * to return the matching value.
@@ -52,7 +54,7 @@
  * Trie is required external locks need to be applied.
  * </p>
  * 
- * @param <V>
+ * @param <V> the Entry type 
  */
 public class ArrayTernaryTrie<V> extends AbstractTrie<V>
 {
@@ -141,8 +143,8 @@ public ArrayTernaryTrie(boolean insensitive, int capacity)
 
     /* ------------------------------------------------------------ */
     /** Copy Trie and change capacity by a factor
-     * @param trie
-     * @param factor
+     * @param trie the trie to copy from
+     * @param factor the factor to grow the capacity by
      */
     public ArrayTernaryTrie(ArrayTernaryTrie<V> trie, double factor)
     {

jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java

@@ -44,7 +44,7 @@
  * and not mutated during that access.  If concurrent mutations of the
  * Trie is required external locks need to be applied.
  * </p>
- * @param <V>
+ * @param <V> the entry type
  */
 public class ArrayTrie<V> extends AbstractTrie<V>
 {

jetty-util/src/main/java/org/eclipse/jetty/util/ArrayUtil.java

@@ -25,8 +25,8 @@
 import java.util.List;
 
 
-/* ------------------------------------------------------------ */
 /**
+ * Utility methods for Array manipulation
  */
 public class ArrayUtil
     implements Cloneable, Serializable
@@ -60,6 +60,7 @@ public static<T> T[] removeFromArray(T[] array, Object item)
      * @param item The item to add
      * @param type The type of the array (in case of null array)
      * @return new array with contents of array plus item
+     * @param <T> the array entry type
      */
     public static<T> T[] addToArray(T[] array, T item, Class<?> type)
     {
@@ -86,6 +87,7 @@ public static<T> T[] addToArray(T[] array, T item, Class<?> type)
      * @param item The item to add
      * @param type The type of the array (in case of null array)
      * @return new array with contents of array plus item
+     * @param <T> the array entry type
      */
     public static<T> T[] prependToArray(T item, T[] array, Class<?> type)
     {
@@ -113,6 +115,7 @@ public static<T> T[] prependToArray(T item, T[] array, Class<?> type)
     /**
      * @param array Any array of object
      * @return A new <i>modifiable</i> list initialised with the elements from <code>array</code>.
+     * @param <E> the array entry type
      */
     public static<E> List<E> asMutableList(E[] array)
     {	

jetty-util/src/main/java/org/eclipse/jetty/util/BlockingArrayQueue.java

@@ -33,13 +33,16 @@
 
 /**
  * A BlockingQueue backed by a circular array capable or growing.
- * <p/>
+ * <p>
  * This queue is uses a variant of the two lock queue algorithm to provide an efficient queue or list backed by a growable circular array.
- * <p/>
+ * </p>
+ * <p>
  * Unlike {@link java.util.concurrent.ArrayBlockingQueue}, this class is able to grow and provides a blocking put call.
- * <p/>
+ * </p>
+ * <p>
  * The queue has both a capacity (the size of the array currently allocated) and a max capacity (the maximum size that may be allocated), which defaults to
  * {@link Integer#MAX_VALUE}.
+ * </p>
  * 
  * @param <E>
  *            The element type

jetty-util/src/main/java/org/eclipse/jetty/util/BufferUtil.java

@@ -43,10 +43,12 @@
  * The various ByteBuffer methods assume a mode and some of them will switch or enforce a mode:
  * Allocate and clear set fill mode; flip and compact switch modes; read and write assume fill 
  * and flush modes.    This duality can result in confusing code such as:
+ * </p>
  * <pre>
  *     buffer.clear();
  *     channel.write(buffer);
  * </pre>
+ * <p>
  * Which looks as if it should write no data, but in fact writes the buffer worth of garbage.
  * </p>
  * <p>
@@ -58,20 +60,22 @@
  * <p>
  * Thus this class provides alternate implementations of {@link #allocate(int)}, 
  * {@link #allocateDirect(int)} and {@link #clear(ByteBuffer)} that leave the buffer
- * in flush mode.   Thus the following tests will pass:<pre>
+ * in flush mode.   Thus the following tests will pass:
+ * </p>
+ * <pre>
  *     ByteBuffer buffer = BufferUtil.allocate(1024);
  *     assert(buffer.remaining()==0);
  *     BufferUtil.clear(buffer);
  *     assert(buffer.remaining()==0);
  * </pre>
- * </p>
  * <p>If the BufferUtil methods {@link #fill(ByteBuffer, byte[], int, int)}, 
  * {@link #append(ByteBuffer, byte[], int, int)} or {@link #put(ByteBuffer, ByteBuffer)} are used,
  * then the caller does not need to explicitly switch the buffer to fill mode.    
  * If the caller wishes to use other ByteBuffer bases libraries to fill a buffer, 
  * then they can use explicit calls of #flipToFill(ByteBuffer) and #flipToFlush(ByteBuffer, int)
  * to change modes.  Note because this convention attempts to avoid the copies of compact, the position
  * is not set to zero on each fill cycle and so its value must be remembered:
+ * </p>
  * <pre>
  *      int pos = BufferUtil.flipToFill(buffer);
  *      try
@@ -83,8 +87,9 @@
  *          flipToFlush(buffer, pos);
  *      }
  * </pre>
- * The flipToFill method will effectively clear the buffer if it is emtpy and will compact the buffer if there is no space.
- * 
+ * <p>
+ * The flipToFill method will effectively clear the buffer if it is empty and will compact the buffer if there is no space.
+ * </p>
  */
 public class BufferUtil
 {
@@ -355,7 +360,7 @@ public static int flipPutFlip(ByteBuffer from, ByteBuffer to)
      * @param b bytes to append
      * @param off offset into byte
      * @param len length to append
-     * @throws BufferOverflowException
+     * @throws BufferOverflowException if unable to append buffer due to space limits
      */
     public static void append(ByteBuffer to, byte[] b, int off, int len) throws BufferOverflowException
     {
@@ -392,6 +397,7 @@ public static void append(ByteBuffer to, byte b)
     /** Appends a buffer to a buffer
      * @param to Buffer is flush mode
      * @param b buffer to append
+     * @return The position of the valid data before the flipped position.
      */
     public static int append(ByteBuffer to, ByteBuffer b)
     {
@@ -413,6 +419,7 @@ public static int append(ByteBuffer to, ByteBuffer b)
      * @param b bytes to fill
      * @param off offset into byte
      * @param len length to fill
+     * @return The position of the valid data before the flipped position.
      */
     public static int fill(ByteBuffer to, byte[] b, int off, int len)
     {
@@ -523,6 +530,7 @@ public static String toString(ByteBuffer buffer, Charset charset)
     /* ------------------------------------------------------------ */
     /** Convert a partial buffer to a String.
      * 
+     * @param buffer the buffer to convert 
      * @param position The position in the buffer to start the string from
      * @param length The length of the buffer
      * @param charset The {@link Charset} to use to convert the bytes
@@ -560,11 +568,16 @@ public static int toInt(ByteBuffer buffer)
 
     /* ------------------------------------------------------------ */
     /**
-     * Convert buffer to an integer. Parses up to the first non-numeric character. If no number is found an IllegalArgumentException is thrown
+     * Convert buffer to an integer. Parses up to the first non-numeric character. If no number is found an
+     * IllegalArgumentException is thrown
      *
      * @param buffer
      *            A buffer containing an integer in flush mode. The position is not changed.
-     * @return an int
+     * @param position
+     *            the position in the buffer to start reading from
+     * @param length
+     *            the length of the buffer to use for conversion
+     * @return an int of the buffer bytes
      */
     public static int toInt(ByteBuffer buffer, int position, int length)
     {
@@ -952,8 +965,6 @@ public static String toDetailString(ByteBuffer[] buffer)
 
     /* ------------------------------------------------------------ */
     /** Convert Buffer to string ID independent of content
-     * @param buffer
-     * @return A string showing the buffer ID
      */
     private static void idString(ByteBuffer buffer, StringBuilder out) 
     {
@@ -974,7 +985,7 @@ private static void idString(ByteBuffer buffer, StringBuilder out)
 
     /* ------------------------------------------------------------ */
     /** Convert Buffer to string ID independent of content
-     * @param buffer
+     * @param buffer the buffet to generate a string ID from
      * @return A string showing the buffer ID
      */
     public static String toIDString(ByteBuffer buffer)
@@ -987,7 +998,7 @@ public static String toIDString(ByteBuffer buffer)
 
     /* ------------------------------------------------------------ */
     /** Convert Buffer to a detail debug string of pointers and content
-     * @param buffer
+     * @param buffer the buffer to generate a detail string from
      * @return A string showing the pointers and content of the buffer
      */
     public static String toDetailString(ByteBuffer buffer)
@@ -1069,7 +1080,7 @@ else if (b == '\t')
 
     /* ------------------------------------------------------------ */
     /** Convert buffer to a Hex Summary String.
-     * @param buffer
+     * @param buffer the buffer to generate a hex byte summary from
      * @return A string showing the escaped content of the buffer around the
      * position and limit (marked with &lt;&lt;&lt; and &gt;&gt;&gt;)
      */

jetty-util/src/main/java/org/eclipse/jetty/util/CompletableCallback.java

@@ -21,16 +21,18 @@
 import java.util.concurrent.atomic.AtomicReference;
 
 /**
+ * <p>
  * A callback to be used by driver code that needs to know whether the callback has been
  * succeeded or failed (that is, completed) just after the asynchronous operation or not,
  * typically because further processing depends on the callback being completed.
  * The driver code competes with the asynchronous operation to complete the callback.
- * <p />
+ * </p>
+ * <p>
  * If the callback is already completed, the driver code continues the processing,
  * otherwise it suspends it. If it is suspended, the callback will be completed some time
  * later, and {@link #resume()} or {@link #abort(Throwable)} will be called to allow the
  * application to resume the processing.
- * <p />
+ * </p>
  * Typical usage:
  * <pre>
  * CompletableCallback callback = new CompletableCallback()
@@ -124,6 +126,7 @@ public void failed(Throwable x)
 
     /**
      * Callback method invoked when this callback is failed.
+     * @param failure the throwable reprsenting the callback failure
      */
     public abstract void abort(Throwable failure);
 

jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java

@@ -34,14 +34,16 @@
 /**
  * A concurrent, unbounded implementation of {@link Queue} that uses singly-linked array blocks
  * to store elements.
- * <p/>
+ * <p>
  * This class is a drop-in replacement for {@link ConcurrentLinkedQueue}, with similar performance
  * but producing less garbage because arrays are used to store elements rather than nodes.
- * <p/>
+ * </p>
+ * <p>
  * The algorithm used is a variation of the algorithm from Gidenstam, Sundell and Tsigas
  * (http://www.adm.hb.se/~AGD/Presentations/CacheAwareQueue_OPODIS.pdf).
+ * </p>
  *
- * @param <T>
+ * @param <T> the Array entry type
  */
 public class ConcurrentArrayQueue<T> extends AbstractQueue<T>
 {

jetty-util/src/main/java/org/eclipse/jetty/util/DateCache.java

@@ -23,7 +23,6 @@
 import java.util.Locale;
 import java.util.TimeZone;
 
-/* ------------------------------------------------------------ */
 /**  Date Format Cache.
  * Computes String representations of Dates and caches
  * the results so that subsequent requests within the same second
@@ -37,9 +36,7 @@
  *
  * If consecutive calls are frequently very different, then this
  * may be a little slower than a normal DateFormat.
- *
  */
-
 public class DateCache
 {
     public static final String DEFAULT_FORMAT="EEE MMM dd HH:mm:ss zzz yyyy";
@@ -77,6 +74,7 @@ public DateCache()
     /* ------------------------------------------------------------ */
     /** Constructor.
      * Make a DateCache that will use the given format
+     * @param format the format to use
      */
     public DateCache(String format)
     {
@@ -161,7 +159,7 @@ public TimeZone getTimeZone()
 
     /* ------------------------------------------------------------ */
     /** Format a date according to our stored formatter.
-     * @param inDate 
+     * @param inDate the Date
      * @return Formatted date
      */
     public String format(Date inDate)
@@ -187,7 +185,7 @@ public String format(Date inDate)
     /** Format a date according to our stored formatter.
      * If it happens to be in the same second as the last formatNow
      * call, then the format is reused.
-     * @param inDate 
+     * @param inDate the date in milliseconds since unix epoch 
      * @return Formatted date
      */
     public String format(long inDate)
@@ -215,7 +213,7 @@ public String format(long inDate)
      * The passed time is expected to be close to the current time, so it is 
      * compared to the last value passed and if it is within the same second,
      * the format is reused.  Otherwise a new cached format is created.
-     * @param now 
+     * @param now the milliseconds since unix epoch 
      * @return Formatted date
      */
     public String formatNow(long now)

jetty-util/src/main/java/org/eclipse/jetty/util/HostMap.java

@@ -23,8 +23,8 @@
 import java.util.HashSet;
 import java.util.Map;
 
-/* ------------------------------------------------------------ */
 /**
+ * @param <TYPE> the element type
  */
 @SuppressWarnings("serial")
 public class HostMap<TYPE> extends HashMap<String, TYPE>