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.ByteBuffer;
 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 @@ import java.util.Queue;
 /* ------------------------------------------------------------ */
 /**
  * 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.HashSet;
 import java.util.Set;
 
 
-/* ------------------------------------------------------------ */
 /** 
  * <p>A Ternary Trie String lookup data structure.</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>
- * The Trie is stored in 3 arrays:<dl>
+ * 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:
+ * </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 @@ import java.util.Set;
  * 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 class ArrayTernaryTrie<V> extends AbstractTrie<V>
 
     /* ------------------------------------------------------------ */
     /** Copy Trie and change capacity by a factor
-     * @param trie
+     * @param trie the trie to copy from
-     * @param factor
+     * @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 @@ import java.util.Set;
  * 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.Arrays;
 import java.util.List;
 
 
-/* ------------------------------------------------------------ */
 /**
+ * Utility methods for Array manipulation
  */
 public class ArrayUtil
     implements Cloneable, Serializable
@@ -60,6 +60,7 @@ public class ArrayUtil
      * @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 class ArrayUtil
      * @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 class ArrayUtil
     /**
      * @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 @@ import java.util.concurrent.locks.ReentrantLock;
 
 /**
  * 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 @@ import org.eclipse.jetty.util.resource.Resource;
  * 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,13 +60,14 @@ import org.eclipse.jetty.util.resource.Resource;
  * <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.    
@@ -72,6 +75,7 @@ import org.eclipse.jetty.util.resource.Resource;
  * 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 @@ import org.eclipse.jetty.util.resource.Resource;
  *          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 class BufferUtil
      * @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 class BufferUtil
     /** 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 class BufferUtil
      * @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 class BufferUtil
     /* ------------------------------------------------------------ */
     /** 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 class BufferUtil
 
     /* ------------------------------------------------------------ */
     /**
-     * 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 class BufferUtil
     
     /* ------------------------------------------------------------ */
     /** 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 @@ public class BufferUtil
     
     /* ------------------------------------------------------------ */
     /** 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 class BufferUtil
     
     /* ------------------------------------------------------------ */
     /** 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 @@ public class BufferUtil
 
     /* ------------------------------------------------------------ */
     /** 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 @@ package org.eclipse.jetty.util;
 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 abstract class CompletableCallback implements Callback
 
     /**
      * 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 @@ import java.util.concurrent.atomic.AtomicReferenceArray;
 /**
  * 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.Date;
 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 @@ import java.util.TimeZone;
  *
  * 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 class 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 class DateCache
 
     /* ------------------------------------------------------------ */
     /** 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 class DateCache
     /** 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 class DateCache
      * 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.HashMap;
 import java.util.HashSet;
 import java.util.Map;
 
-/* ------------------------------------------------------------ */
 /**
+ * @param <TYPE> the element type
  */
 @SuppressWarnings("serial")
 public class HostMap<TYPE> extends HashMap<String, TYPE>

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

@@ -108,6 +108,9 @@ public class IO
     
     /* ------------------------------------------------------------------- */
     /** Copy Stream in to Stream out until EOF or exception.
+     * @param in the input stream to read from (until EOF)
+     * @param out the output stream to write to
+     * @throws IOException if unable to copy streams 
      */
     public static void copy(InputStream in, OutputStream out)
          throws IOException
@@ -117,6 +120,9 @@ public class IO
     
     /* ------------------------------------------------------------------- */
     /** Copy Reader to Writer out until EOF or exception.
+     * @param in the read to read from (until EOF)
+     * @param out the writer to write to
+     * @throws IOException if unable to copy the streams
      */
     public static void copy(Reader in, Writer out)
          throws IOException
@@ -126,6 +132,10 @@ public class IO
     
     /* ------------------------------------------------------------------- */
     /** Copy Stream in to Stream for byteCount bytes or until EOF or exception.
+     * @param in the stream to read from
+     * @param out the stream to write to
+     * @param byteCount the number of bytes to copy
+     * @throws IOException if unable to copy the streams
      */
     public static void copy(InputStream in,
                             OutputStream out,
@@ -163,6 +173,10 @@ public class IO
     
     /* ------------------------------------------------------------------- */
     /** Copy Reader to Writer for byteCount bytes or until EOF or exception.
+     * @param in the Reader to read from
+     * @param out the Writer to write to
+     * @param byteCount the number of bytes to copy
+     * @throws IOException if unable to copy streams
      */
     public static void copy(Reader in,
                             Writer out,
@@ -213,9 +227,9 @@ public class IO
 
     /* ------------------------------------------------------------ */
     /** Copy files or directories
-     * @param from
+     * @param from the file to copy
-     * @param to
+     * @param to the destination to copy to
-     * @throws IOException
+     * @throws IOException if unable to copy
      */
     public static void copy(File from,File to) throws IOException
     {
@@ -261,6 +275,9 @@ public class IO
     
     /* ------------------------------------------------------------ */
     /** Read input stream to string.
+     * @param in the stream to read from (until EOF)
+     * @return the String parsed from stream (default Charset)
+     * @throws IOException if unable to read the stream (or handle the charset)
      */
     public static String toString(InputStream in)
         throws IOException
@@ -270,6 +287,10 @@ public class IO
     
     /* ------------------------------------------------------------ */
     /** Read input stream to string.
+     * @param in the stream to read from (until EOF)
+     * @param encoding the encoding to use (can be null to use default Charset)
+     * @return the String parsed from the stream
+     * @throws IOException if unable to read the stream (or handle the charset) 
      */
     public static String toString(InputStream in,String encoding)
         throws IOException
@@ -278,6 +299,10 @@ public class IO
     }
 
     /** Read input stream to string.
+     * @param in the stream to read from (until EOF)
+     * @param encoding the Charset to use (can be null to use default Charset)
+     * @return the String parsed from the stream
+     * @throws IOException if unable to read the stream (or handle the charset) 
      */
     public static String toString(InputStream in, Charset encoding)
             throws IOException
@@ -291,6 +316,9 @@ public class IO
 
     /* ------------------------------------------------------------ */
     /** Read input stream to string.
+     * @param in the reader to read from (until EOF)
+     * @return the String parsed from the reader
+     * @throws IOException if unable to read the stream (or handle the charset) 
      */
     public static String toString(Reader in)
         throws IOException
@@ -304,7 +332,8 @@ public class IO
     /* ------------------------------------------------------------ */
     /** Delete File.
      * This delete will recursively delete directories - BE CAREFULL
-     * @param file The file to be deleted.
+     * @param file The file (or directory) to be deleted.
+     * @return true if anything was deleted. (note: this does not mean that all content in a directory was deleted)
      */
     public static boolean delete(File file)
     {

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

@@ -35,11 +35,12 @@ import java.util.StringTokenizer;
  *     nnn  - an absolute value (0-255)
  * mmm-nnn  - an inclusive range of absolute values, 
  *            with following shorthand notations:
- *           nnn- => nnn-255
+ *              nnn- => nnn-255
- *           -nnn => 0-nnn
+ *             -nnn  => 0-nnn
- *           -    => 0-255
+ *             -     => 0-255
  *          a,b,...  - a list of wildcard specifications
  * </pre>
+ * @param <TYPE> the Map Entry value type
  */
 @SuppressWarnings("serial")
 public class IPAddressMap<TYPE> extends HashMap<String, TYPE>

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

@@ -26,29 +26,33 @@ import org.eclipse.jetty.util.thread.SpinLock;
  * This specialized callback implements a pattern that allows
  * a large job to be broken into smaller tasks using iteration
  * rather than recursion.
- * <p/>
+ * <p>
  * A typical example is the write of a large content to a socket,
  * divided in chunks. Chunk C1 is written by thread T1, which
  * also invokes the callback, which writes chunk C2, which invokes
  * the callback again, which writes chunk C3, and so forth.
- * <p/>
+ * </p>
+ * <p>
  * The problem with the example is that if the callback thread
  * is the same that performs the I/O operation, then the process
  * is recursive and may result in a stack overflow.
  * To avoid the stack overflow, a thread dispatch must be performed,
  * causing context switching and cache misses, affecting performance.
- * <p/>
+ * </p>
+ * <p>
  * To avoid this issue, this callback uses an AtomicReference to
  * record whether success callback has been called during the processing
  * of a sub task, and if so then the processing iterates rather than
  * recurring.
- * <p/>
+ * </p>
+ * <p>
  * Subclasses must implement method {@link #process()} where the sub
  * task is executed and a suitable {@link IteratingCallback.Action} is
  * returned to this callback to indicate the overall progress of the job.
  * This callback is passed to the asynchronous execution of each sub
  * task and a call the {@link #succeeded()} on this callback represents
  * the completion of the sub task.
+ * </p>
  */
 public abstract class IteratingCallback implements Callback
 {
@@ -138,9 +142,10 @@ public abstract class IteratingCallback implements Callback
     
     /**
      * Method called by {@link #iterate()} to process the sub task.
-     * <p/>
+     * <p>
      * Implementations must start the asynchronous execution of the sub task
      * (if any) and return an appropriate action:
+     * </p>
      * <ul>
      * <li>{@link Action#IDLE} when no sub tasks are available for execution
      * but the overall job is not completed yet</li>
@@ -149,6 +154,8 @@ public abstract class IteratingCallback implements Callback
      * <li>{@link Action#SUCCEEDED} when the overall job is completed</li>
      * </ul>
      * 
+     * @return the appropriate Action 
+     *
      * @throws Exception if the sub task processing throws
      */
     protected abstract Action process() throws Exception;
@@ -164,10 +171,11 @@ public abstract class IteratingCallback implements Callback
     
     /**
      * Invoked when the overall task has completed with a failure.
+     * @param cause the throwable to indicate cause of failure
      *
      * @see #onCompleteSuccess()
      */
-    protected void onCompleteFailure(Throwable x)
+    protected void onCompleteFailure(Throwable cause)
     {
     }
 
@@ -464,9 +472,10 @@ public abstract class IteratingCallback implements Callback
 
     /**
      * Resets this callback.
-     * <p/>
+     * <p>
      * A callback can only be reset to IDLE from the
      * SUCCEEDED or FAILED states or if it is already IDLE.
+     * </p>
      *
      * @return true if the reset was successful
      */

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

@@ -27,21 +27,23 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.ListIterator;
 
-/* ------------------------------------------------------------ */
+/** 
-/** Lazy List creation.
+ * Lazy List creation.
+ * <p>
  * A List helper class that attempts to avoid unnecessary List
  * creation.   If a method needs to create a List to return, but it is
  * expected that this will either be empty or frequently contain a
  * single item, then using LazyList will avoid additional object
  * creations by using {@link Collections#EMPTY_LIST} or
  * {@link Collections#singletonList(Object)} where possible.
+ * </p>
  * <p>
  * LazyList works by passing an opaque representation of the list in
  * and out of all the LazyList methods.  This opaque object is either
  * null for an empty list, an Object for a list with a single entry
  * or an {@link ArrayList} for a list of items.
- *
+ * </p>
- * <p><h4>Usage</h4>
+ * <strong>Usage</strong>
  * <pre>
  *   Object lazylist =null;
  *   while(loopCondition)
@@ -162,7 +164,9 @@ public class LazyList
 
     /* ------------------------------------------------------------ */
     /** Ensure the capacity of the underlying list.
-     * 
+     * @param list the list to grow 
+     * @param initialSize the size to grow to
+     * @return the new List with new size
      */
     public static Object ensureSize(Object list, int initialSize)
     {
@@ -230,6 +234,7 @@ public class LazyList
      * @param list A LazyList returned from LazyList.add(Object)
      * @return The List of added items, which may be an EMPTY_LIST
      * or a SingletonList.
+     * @param <E> the list entry type
      */
     public static<E> List<E> getList(Object list)
     {
@@ -245,6 +250,7 @@ public class LazyList
      * empty list.
      * @return The List of added items, which may be null, an EMPTY_LIST
      * or a SingletonList.
+     * @param <E> the list entry type
      */
     @SuppressWarnings("unchecked")
     public static<E> List<E> getList(Object list, boolean nullForEmpty)
@@ -365,6 +371,7 @@ public class LazyList
      * @param list  A LazyList returned from LazyList.add(Object) or null
      * @param i int index
      * @return the item from the list.
+     * @param <E> the list entry type
      */
     @SuppressWarnings("unchecked")
     public static <E> E get(Object list, int i)

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

@@ -69,10 +69,10 @@ public class Loader
     /* ------------------------------------------------------------ */
     /** Load a class.
      * 
-     * @param loadClass
+     * @param loadClass the class to use for the ClassLoader that was used
-     * @param name
+     * @param name the name of the new class to load, using the same ClassLoader as the <code>loadClass</code> 
      * @return Class
-     * @throws ClassNotFoundException
+     * @throws ClassNotFoundException if not able to find the class
      */
     @SuppressWarnings("rawtypes")
     public static Class loadClass(Class loadClass,String name)
@@ -153,7 +153,9 @@ public class Loader
      * above the given classloader.
      * 
      * This is primarily used for jasper.
+     * @param loader the classloader to use
      * @return the system class path
+     * @throws Exception if unable to generate the classpath from the resource references
      */
     public static String getClassPath(ClassLoader loader) throws Exception
     {

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

@@ -22,8 +22,7 @@ import java.security.AccessController;
 import java.security.PrivilegedAction;
 
 /**
- * {@link MemoryUtils} provides an abstraction over memory properties and operations.
+ * MemoryUtils provides an abstraction over memory properties and operations.
- * <p />
  */
 public class MemoryUtils
 {
@@ -67,5 +66,4 @@ public class MemoryUtils
     {
         return getCacheLineBytes() >> 3;
     }
-
 }

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

@@ -84,7 +84,7 @@ public class MultiException extends Exception
      * If this multi exception is empty then no action is taken. If it
      * contains a single exception that is thrown, otherwise the this
      * multi exception is thrown. 
-     * @exception Exception 
+     * @exception Exception the Error or Exception if nested is 1, or the MultiException itself if nested is more than 1.
      */
     public void ifExceptionThrow()
         throws Exception
@@ -144,6 +144,7 @@ public class MultiException extends Exception
      * If this multi exception is empty then no action is taken. If it
      * contains a any exceptions then this
      * multi exception is thrown. 
+     * @throws MultiException the multiexception if there are nested exception
      */
     public void ifExceptionThrowMulti()
         throws MultiException

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

@@ -28,6 +28,7 @@ import java.util.Map.Entry;
 
 /** 
  * A multi valued Map.
+ * @param <V> the entry type for multimap values
  */
 @SuppressWarnings("serial")
 public class MultiMap<V> extends HashMap<String,List<V>>
@@ -283,7 +284,7 @@ public class MultiMap<V> extends HashMap<String,List<V>>
      * Test for a specific single value in the map.
      * <p>
      * NOTE: This is a SLOW operation, and is actively discouraged.
-     * @param value
+     * @param value the value to search for
      * @return true if contains simple value
      */
     public boolean containsSimpleValue(V value)

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

@@ -293,7 +293,7 @@ public class MultiPartInputStreamParser
         /**
          * Only remove tmp files.
          * 
-         * @throws IOException
+         * @throws IOException if unable to delete the file
          */
         public void cleanUp() throws IOException
         {
@@ -303,7 +303,8 @@ public class MultiPartInputStreamParser
 
 
         /**
-         * Get the file, if any, the data has been written to.
+         * Get the file
+         * @return the file, if any, the data has been written to.
          */
         public File getFile ()
         {
@@ -345,6 +346,7 @@ public class MultiPartInputStreamParser
 
     /**
      * Get the already parsed parts.
+     * @return the parts that were parsed
      */
     public Collection<Part> getParsedParts()
     {
@@ -364,7 +366,7 @@ public class MultiPartInputStreamParser
     /**
      * Delete any tmp storage for parts, and clear out the parts list.
      * 
-     * @throws MultiException
+     * @throws MultiException if unable to delete the parts
      */
     public void deleteParts ()
     throws MultiException
@@ -391,8 +393,9 @@ public class MultiPartInputStreamParser
     /**
      * Parse, if necessary, the multipart data and return the list of Parts.
      * 
-     * @throws IOException
+     * @return the parts 
-     * @throws ServletException
+     * @throws IOException if unable to get the parts
+     * @throws ServletException if unable to parse the parts
      */
     public Collection<Part> getParts()
     throws IOException, ServletException
@@ -412,9 +415,10 @@ public class MultiPartInputStreamParser
     /**
      * Get the named Part.
      * 
-     * @param name
+     * @param name the part name
-     * @throws IOException
+     * @return the parts
-     * @throws ServletException
+     * @throws IOException if unable to get the part
+     * @throws ServletException if unable to parse the parts
      */
     public Part getPart(String name)
     throws IOException, ServletException
@@ -427,8 +431,8 @@ public class MultiPartInputStreamParser
     /**
      * Parse, if necessary, the multipart stream.
      * 
-     * @throws IOException
+     * @throws IOException if unable to parse
-     * @throws ServletException
+     * @throws ServletException FIXME, never thrown
      */
     protected void parse ()
     throws IOException, ServletException

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

@@ -24,7 +24,6 @@ import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
 
 
-/* ================================================================ */
 /** Handle a multipart MIME response.
  *
  * 
@@ -100,6 +99,8 @@ public class MultiPartOutputStream extends FilterOutputStream
     
     /* ------------------------------------------------------------ */
     /** Start creation of the next Content.
+     * @param contentType the content type of the part
+     * @throws IOException if unable to write the part
      */
     public void startPart(String contentType)
          throws IOException
@@ -118,6 +119,9 @@ public class MultiPartOutputStream extends FilterOutputStream
         
     /* ------------------------------------------------------------ */
     /** Start creation of the next Content.
+     * @param contentType the content type of the part
+     * @param headers the part headers
+     * @throws IOException if unable to write the part
      */
     public void startPart(String contentType, String[] headers)
          throws IOException

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

@@ -87,6 +87,8 @@ public class MultiPartWriter extends FilterWriter
     
     /* ------------------------------------------------------------ */
     /** Start creation of the next Content.
+     * @param contentType the content type
+     * @throws IOException if unable to write the part
      */
     public void startPart(String contentType)
          throws IOException
@@ -105,6 +107,7 @@ public class MultiPartWriter extends FilterWriter
     
     /* ------------------------------------------------------------ */
     /** end creation of the next Content.
+     * @throws IOException if unable to write the part
      */
     public void endPart()
          throws IOException
@@ -116,6 +119,9 @@ public class MultiPartWriter extends FilterWriter
         
     /* ------------------------------------------------------------ */
     /** Start creation of the next Content.
+     * @param contentType the content type of the part
+     * @param headers the part headers
+     * @throws IOException if unable to write the part
      */
     public void startPart(String contentType, String[] headers)
          throws IOException

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

@@ -53,7 +53,7 @@ public abstract class PatternMatcher
      * @param pattern the pattern
      * @param uris the uris to test the pattern against
      * @param isNullInclusive if true, an empty pattern means all names match, if false, none match
-     * @throws Exception
+     * @throws Exception if fundamental error in pattern matching
      */
     public void match (Pattern pattern, URI[] uris, boolean isNullInclusive)
     throws Exception

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

@@ -472,6 +472,7 @@ public class QuotedStringTokenizer
     /* ------------------------------------------------------------ */
     /** Unquote a string.
      * @param s The string to unquote.
+     * @param lenient true if unquoting should be lenient to escaped content, leaving some alone, false if string unescaping
      * @return quoted string
      */
     public static String unquote(String s, boolean lenient)

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

@@ -40,8 +40,6 @@ import java.util.TimerTask;
  * actual date when creating and rolling over the file.
  * 
  * Old files are retained for a number of days before being deleted.
- * 
- * 
  */
 public class RolloverFileOutputStream extends FilterOutputStream
 {
@@ -65,7 +63,7 @@ public class RolloverFileOutputStream extends FilterOutputStream
     /**
      * @param filename The filename must include the string "yyyy_mm_dd", 
      * which is replaced with the actual date when creating and rolling over the file.
-     * @throws IOException
+     * @throws IOException if unable to create output
      */
     public RolloverFileOutputStream(String filename)
         throws IOException
@@ -78,7 +76,7 @@ public class RolloverFileOutputStream extends FilterOutputStream
      * @param filename The filename must include the string "yyyy_mm_dd", 
      * which is replaced with the actual date when creating and rolling over the file.
      * @param append If true, existing files will be appended to.
-     * @throws IOException
+     * @throws IOException if unable to create output
      */
     public RolloverFileOutputStream(String filename, boolean append)
         throws IOException
@@ -92,7 +90,7 @@ public class RolloverFileOutputStream extends FilterOutputStream
      * which is replaced with the actual date when creating and rolling over the file.
      * @param append If true, existing files will be appended to.
      * @param retainDays The number of days to retain files before deleting them.  0 to retain forever.
-     * @throws IOException
+     * @throws IOException if unable to create output
      */
     public RolloverFileOutputStream(String filename,
                                     boolean append,
@@ -108,7 +106,8 @@ public class RolloverFileOutputStream extends FilterOutputStream
      * which is replaced with the actual date when creating and rolling over the file.
      * @param append If true, existing files will be appended to.
      * @param retainDays The number of days to retain files before deleting them. 0 to retain forever.
-     * @throws IOException
+     * @param zone the timezone for the output
+     * @throws IOException if unable to create output
      */
     public RolloverFileOutputStream(String filename,
                                     boolean append,
@@ -126,9 +125,10 @@ public class RolloverFileOutputStream extends FilterOutputStream
      * which is replaced with the actual date when creating and rolling over the file.
      * @param append If true, existing files will be appended to.
      * @param retainDays The number of days to retain files before deleting them. 0 to retain forever.
+     * @param zone the timezone for the output
      * @param dateFormat The format for the date file substitution. The default is "yyyy_MM_dd". 
      * @param backupFormat The format for the file extension of backup files. The default is "HHmmssSSS". 
-     * @throws IOException
+     * @throws IOException if unable to create output
      */
     public RolloverFileOutputStream(String filename,
                                     boolean append,

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

@@ -221,7 +221,7 @@ public class Scanner extends AbstractLifeCycle
     /**
      * Apply a filter to files found in the scan directory.
      * Only files matching the filter will be reported as added/changed/removed.
-     * @param filter
+     * @param filter the filename filter to use
      */
     public void setFilenameFilter (FilenameFilter filter)
     {
@@ -257,7 +257,7 @@ public class Scanner extends AbstractLifeCycle
     
     /* ------------------------------------------------------------ */
     /** Set if found directories should be reported.
-     * @param dirs
+     * @param dirs true to report directory changes as well
      */
     public void setReportDirs(boolean dirs)
     {
@@ -273,7 +273,7 @@ public class Scanner extends AbstractLifeCycle
     /* ------------------------------------------------------------ */
     /**
      * Add an added/removed/changed listener
-     * @param listener
+     * @param listener the listener to add
      */
     public synchronized void addListener (Listener listener)
     {
@@ -370,6 +370,7 @@ public class Scanner extends AbstractLifeCycle
     }
 
     /**
+     * @param path tests if the path exists
      * @return true if the path exists in one of the scandirs
      */
     public boolean exists(String path)

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

@@ -33,7 +33,7 @@ import org.eclipse.jetty.util.log.Logger;
 /**
  * Provides a reusable {@link Callback} that can block the thread
  * while waiting to be completed.
- * <p />
+ * <p>
  * A typical usage pattern is:
  * <pre>
  * void someBlockingCall(Object... args) throws IOException

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

@@ -33,12 +33,12 @@ import org.eclipse.jetty.util.thread.Scheduler;
 /**
  * Creates asynchronously {@link SocketAddress} instances, returning them through a {@link Promise},
  * in order to avoid blocking on DNS lookup.
- * <p />
+ * <p>
  * {@link InetSocketAddress#InetSocketAddress(String, int)} attempts to perform a DNS resolution of
  * the host name, and this may block for several seconds.
  * This class creates the {@link InetSocketAddress} in a separate thread and provides the result
  * through a {@link Promise}, with the possibility to specify a timeout for the operation.
- * <p />
+ * <p>
  * Example usage:
  * <pre>
  * SocketAddressResolver resolver = new SocketAddressResolver(executor, scheduler);

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

@@ -64,6 +64,8 @@ public class StringUtil
     /* ------------------------------------------------------------ */
     /** Convert alternate charset names (eg utf8) to normalized
      * name (eg UTF-8).
+     * @param s the charset to normalize
+     * @return the normalized charset (or null if normalized version not found)
      */
     public static String normalizeCharset(String s)
     {
@@ -74,6 +76,10 @@ public class StringUtil
     /* ------------------------------------------------------------ */
     /** Convert alternate charset names (eg utf8) to normalized
      * name (eg UTF-8).
+     * @param s the charset to normalize
+     * @param offset the offset in the charset
+     * @param length the length of the charset in the input param
+     * @return the normalized charset (or null if not found)
      */
     public static String normalizeCharset(String s,int offset,int length)
     {
@@ -199,6 +205,9 @@ public class StringUtil
     /* ------------------------------------------------------------ */
     /**
      * returns the next index of a character from the chars string
+     * @param s the input string to search
+     * @param chars the chars to look for
+     * @return the index of the character in the input stream found.
      */
     public static int indexFrom(String s,String chars)
     {
@@ -211,6 +220,10 @@ public class StringUtil
     /* ------------------------------------------------------------ */
     /**
      * replace substrings within string.
+     * @param s the input string
+     * @param sub the string to look for
+     * @param with the string to replace with
+     * @return the now replaced string
      */
     public static String replace(String s, String sub, String with)
     {
@@ -238,6 +251,8 @@ public class StringUtil
 
     /* ------------------------------------------------------------ */
     /** Remove single or double quotes.
+     * @param s the input string
+     * @return the string with quotes removed
      */
     public static String unquote(String s)
     {
@@ -273,6 +288,9 @@ public class StringUtil
     /* ------------------------------------------------------------ */
     /**
      * append hex digit
+     * @param buf the buffer to append to
+     * @param b the byte to append
+     * @param base the base of the hex output (almost always 16).
      * 
      */
     public static void append(StringBuilder buf,byte b,int base)
@@ -289,6 +307,12 @@ public class StringUtil
     }
 
     /* ------------------------------------------------------------ */
+    /**
+     * Append 2 digits (zero padded) to the StringBuffer
+     * 
+     * @param buf the buffer to append to
+     * @param i the value to append
+     */
     public static void append2digits(StringBuffer buf,int i)
     {
         if (i<100)
@@ -299,6 +323,12 @@ public class StringUtil
     }
     
     /* ------------------------------------------------------------ */
+    /**
+     * Append 2 digits (zero padded) to the StringBuilder
+     * 
+     * @param buf the buffer to append to
+     * @param i the value to append
+     */
     public static void append2digits(StringBuilder buf,int i)
     {
         if (i<100)
@@ -501,6 +531,8 @@ public class StringUtil
      * http://en.wikipedia.org/wiki/Security_Identifier
      * 
      * S-1-IdentifierAuthority-SubAuthority1-SubAuthority2-...-SubAuthorityn
+     * @param sidBytes the SID bytes to build from
+     * @return the string SID
      */
     public static String sidBytesToString(byte[] sidBytes)
     {
@@ -548,6 +580,8 @@ public class StringUtil
      * http://en.wikipedia.org/wiki/Security_Identifier
      * 
      * S-1-IdentifierAuthority-SubAuthority1-SubAuthority2-...-SubAuthorityn
+     * @param sidString the string SID
+     * @return the binary SID
      */
     public static byte[] sidStringToBytes( String sidString )
     {

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

@@ -39,7 +39,7 @@ import java.util.Set;
  * Trie is required external locks need to be applied.
  * </p>
  * 
- * @param <V>
+ * @param <V> the entry type
  */
 public class TreeTrie<V> extends AbstractTrie<V>
 {

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

@@ -24,7 +24,7 @@ import java.util.Set;
 
 /* ------------------------------------------------------------ */
 /** A Trie String lookup data structure.
- * @param <V>
+ * @param <V> the Trie entry type
  */
 public interface Trie<V>
 {
@@ -49,6 +49,7 @@ public interface Trie<V>
     /* ------------------------------------------------------------ */
     /** Get and exact match from a String key
      * @param s The key
+     * @return the value for the string key
      */
     public V get(String s);
 
@@ -57,6 +58,7 @@ public interface Trie<V>
      * @param s The key
      * @param offset The offset within the string of the key
      * @param len the length of the key
+     * @return the value for the string / offset / length
      */
     public V get(String s,int offset,int len);
 

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

@@ -173,7 +173,9 @@ public class TypeUtil
     /** Array to List.
      * <p>
      * Works like {@link Arrays#asList(Object...)}, but handles null arrays.
+     * @param a the array to convert to a list
      * @return a list backed by the array.
+     * @param <T> the array and list entry type
      */
     public static <T> List<T> asList(T[] a)
     {

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

@@ -25,18 +25,20 @@ import org.eclipse.jetty.util.Utf8Appendable.NotUtf8Exception;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-
+/** 
-
+ * URI Utility methods.
-/* ------------------------------------------------------------ */
+ * <p>
-/** URI Utility methods.
  * This class assists with the decoding and encoding or HTTP URI's.
  * It differs from the java.net.URL class as it does not provide
  * communications ability, but it does assist with query string
  * formatting.
- * <P>UTF-8 encoding is used by default for % encoded characters. This
+ * </p>
+ * <p>
+ * UTF-8 encoding is used by default for % encoded characters. This
  * may be overridden with the org.eclipse.jetty.util.URI.charset system property.
- * @see UrlEncoded
+ * </p>
  * 
+ * @see UrlEncoded
  */
 public class URIUtil
     implements Cloneable
@@ -479,6 +481,8 @@ public class URIUtil
     /* ------------------------------------------------------------ */
     /** Return the parent Path.
      * Treat a URI like a directory path and return the parent directory.
+     * @param p the path to return a parent reference to
+     * @return the parent path of the URI
      */
     public static String parentPath(String p)
     {
@@ -494,7 +498,7 @@ public class URIUtil
     /** Convert a path to a cananonical form.
      * All instances of "." and ".." are factored out.  Null is returned
      * if the path tries to .. above its root.
-     * @param path 
+     * @param path the path to convert
      * @return path or null.
      */
     public static String canonicalPath(String path)
@@ -628,8 +632,8 @@ public class URIUtil
     /* ------------------------------------------------------------ */
     /** Convert a path to a compact form.
      * All instances of "//" and "///" etc. are factored out to single "/" 
-     * @param path 
+     * @param path the path to compact 
-     * @return path
+     * @return the compacted path 
      */
     public static String compactPath(String path)
     {
@@ -715,11 +719,11 @@ public class URIUtil
     /* ------------------------------------------------------------ */
     /**
      * Create a new URI from the arguments, handling IPv6 host encoding and default ports
-     * @param scheme
+     * @param scheme the URI scheme
-     * @param server
+     * @param server the URI server
-     * @param port
+     * @param port the URI port
-     * @param path
+     * @param path the URI path
-     * @param query
+     * @param query the URI query
      * @return A String URI
      */
     public static String newURI(String scheme,String server, int port,String path,String query)
@@ -734,9 +738,9 @@ public class URIUtil
     /* ------------------------------------------------------------ */
     /**
      * Create a new URI StringBuilder from the arguments, handling IPv6 host encoding and default ports
-     * @param scheme
+     * @param scheme the URI scheme
-     * @param server
+     * @param server the URI server
-     * @param port
+     * @param port the URI port
      * @return a StringBuilder containing URI prefix
      */
     public static StringBuilder newURIBuilder(String scheme,String server, int port)
@@ -748,11 +752,11 @@ public class URIUtil
 
     /* ------------------------------------------------------------ */
     /** 
-     * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports</p>
+     * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports
      * @param url StringBuilder to append to
-     * @param scheme
+     * @param scheme the URI scheme
-     * @param server
+     * @param server the URI server
-     * @param port
+     * @param port the URI port
      */
     public static void appendSchemeHostPort(StringBuilder url,String scheme,String server, int port)
     {
@@ -783,11 +787,11 @@ public class URIUtil
     
     /* ------------------------------------------------------------ */
     /** 
-     * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports</p>
+     * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports
      * @param url StringBuffer to append to
-     * @param scheme
+     * @param scheme the URI scheme
-     * @param server
+     * @param server the URI server
-     * @param port
+     * @param port the URI port
      */
     public static void appendSchemeHostPort(StringBuffer url,String scheme,String server, int port)
     {

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

@@ -33,22 +33,26 @@ import org.eclipse.jetty.util.Utf8Appendable.NotUtf8Exception;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-/* ------------------------------------------------------------ */
+/** 
-/** Handles coding of MIME  "x-www-form-urlencoded".
+ * Handles coding of MIME  "x-www-form-urlencoded".
  * <p>
  * This class handles the encoding and decoding for either
  * the query string of a URL or the _content of a POST HTTP request.
- *
+ * </p>
- * <h4>Notes</h4>
+ * <b>Notes</b>
+ * <p>
  * The UTF-8 charset is assumed, unless otherwise defined by either
  * passing a parameter or setting the "org.eclipse.jetty.util.UrlEncoding.charset"
  * System property.
+ * </p>
  * <p>
  * The hashtable either contains String single values, vectors
  * of String or arrays of Strings.
+ * </p>
  * <p>
  * This class is only partially synchronised.  In particular, simple
  * get operations are not protected from concurrent updates.
+ * </p>
  *
  * @see java.net.URLEncoder
  */
@@ -103,7 +107,8 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     }
     
     /* -------------------------------------------------------------- */
-    /** Encode Hashtable with % encoding.
+    /** Encode MultiMap with % encoding for UTF8 sequences.
+     * @return the MultiMap as a string with % encoding
      */
     public String encode()
     {
@@ -111,7 +116,9 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     }
     
     /* -------------------------------------------------------------- */
-    /** Encode Hashtable with % encoding.
+    /** Encode MultiMap with % encoding for arbitrary Charset sequences.
+     * @param charset the charset to use for encoding
+     * @return the MultiMap as a string encoded with % encodings
      */
     public String encode(Charset charset)
     {
@@ -119,9 +126,12 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     }
     
     /* -------------------------------------------------------------- */
-    /** Encode Hashtable with % encoding.
+    /** 
+     * Encode MultiMap with % encoding.
+     * @param charset the charset to encode with
      * @param equalsForNullValue if True, then an '=' is always used, even
-     * for parameters without a value. e.g. "blah?a=&b=&c=".
+     * for parameters without a value. e.g. <code>"blah?a=&amp;b=&amp;c="</code>.
+     * @return the MultiMap as a string encoded with % encodings
      */
     public synchronized String encode(Charset charset, boolean equalsForNullValue)
     {
@@ -129,9 +139,12 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     }
     
     /* -------------------------------------------------------------- */
-    /** Encode Hashtable with % encoding.
+    /** Encode MultiMap with % encoding.
+     * @param map the map to encode
+     * @param charset the charset to use for encoding (uses default encoding if null)
      * @param equalsForNullValue if True, then an '=' is always used, even
-     * for parameters without a value. e.g. "blah?a=&b=&c=".
+     * for parameters without a value. e.g. <code>"blah?a=&amp;b=&amp;c="</code>.
+     * @return the MultiMap as a string encoded with % encodings. 
      */
     public static String encode(MultiMap<String> map, Charset charset, boolean equalsForNullValue)
     {
@@ -190,6 +203,8 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     /* -------------------------------------------------------------- */
     /** Decoded parameters to Map.
      * @param content the string containing the encoded parameters
+     * @param map the MultiMap to put parsed query parameters into
+     * @param charset the charset to use for decoding
      */
     public static void decodeTo(String content, MultiMap<String> map, String charset)
     {
@@ -199,6 +214,8 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     /* -------------------------------------------------------------- */
     /** Decoded parameters to Map.
      * @param content the string containing the encoded parameters
+     * @param map the MultiMap to put parsed query parameters into
+     * @param charset the charset to use for decoding
      */
     public static void decodeTo(String content, MultiMap<String> map, Charset charset)
     {
@@ -282,7 +299,7 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     
     /* -------------------------------------------------------------- */
     /** Decoded parameters to Map.
-     * @param raw the byte[] containing the encoded parameters
+     * @param query the string containing the encoded parameters
      * @param offset the offset within raw to decode from
      * @param length the length of the section to decode
      * @param map the {@link MultiMap} to populate
@@ -398,10 +415,13 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     }
 
     /* -------------------------------------------------------------- */
-    /** Decoded parameters to Map.
+    /** Decoded parameters to MultiMap, using ISO8859-1 encodings.
+     * 
      * @param in InputSteam to read
      * @param map MultiMap to add parameters to
-     * @param maxLength maximum number of keys to read or -1 for no limit
+     * @param maxLength maximum length of form to read
+     * @param maxKeys maximum number of keys to read or -1 for no limit
+     * @throws IOException if unable to decode inputstream as ISO8859-1
      */
     public static void decode88591To(InputStream in, MultiMap<String> map, int maxLength, int maxKeys)
     throws IOException
@@ -499,7 +519,9 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     /** Decoded parameters to Map.
      * @param in InputSteam to read
      * @param map MultiMap to add parameters to
-     * @param maxLength maximum number of keys to read or -1 for no limit
+     * @param maxLength maximum form length to decode
+     * @param maxKeys the maximum number of keys to read or -1 for no limit 
+     * @throws IOException if unable to decode input stream
      */
     public static void decodeUtf8To(InputStream in, MultiMap<String> map, int maxLength, int maxKeys)
     throws IOException
@@ -637,6 +659,11 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     /* -------------------------------------------------------------- */
     /** Decoded parameters to Map.
      * @param in the stream containing the encoded parameters
+     * @param map the MultiMap to decode into
+     * @param charset the charset to use for decoding
+     * @param maxLength the maximum length of the form to decode
+     * @param maxKeys the maximum number of keys to decode
+     * @throws IOException if unable to decode input stream
      */
     public static void decodeTo(InputStream in, MultiMap<String> map, String charset, int maxLength, int maxKeys)
     throws IOException
@@ -661,6 +688,11 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     /* -------------------------------------------------------------- */
     /** Decoded parameters to Map.
      * @param in the stream containing the encoded parameters
+     * @param map the MultiMap to decode into
+     * @param charset the charset to use for decoding
+     * @param maxLength the maximum length of the form to decode
+     * @param maxKeys the maximum number of keys to decode
+     * @throws IOException if unable to decode input stream
      */
     public static void decodeTo(InputStream in, MultiMap<String> map, Charset charset, int maxLength, int maxKeys)
     throws IOException
@@ -785,6 +817,8 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     /** Decode String with % encoding.
      * This method makes the assumption that the majority of calls
      * will need no decoding.
+     * @param encoded the encoded string to decode
+     * @return the decoded string
      */
     public static String decodeString(String encoded)
     {
@@ -795,6 +829,11 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     /** Decode String with % encoding.
      * This method makes the assumption that the majority of calls
      * will need no decoding.
+     * @param encoded the encoded string to decode
+     * @param offset the offset in the encoded string to decode from
+     * @param length the length of characters in the encoded string to decode
+     * @param charset the charset to use for decoding
+     * @return the decoded string
      */
     public static String decodeString(String encoded,int offset,int length,Charset charset)
     {
@@ -1012,7 +1051,7 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     
     /* ------------------------------------------------------------ */
     /** Perform URL encoding.
-     * @param string 
+     * @param string the string to encode
      * @return encoded string.
      */
     public static String encodeString(String string)
@@ -1022,7 +1061,8 @@ public class UrlEncoded extends MultiMap<String> implements Cloneable
     
     /* ------------------------------------------------------------ */
     /** Perform URL encoding.
-     * @param string 
+     * @param string the string to encode
+     * @param charset the charset to use for encoding
      * @return encoded string.
      */
     public static String encodeString(String string,Charset charset)

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

@@ -37,7 +37,7 @@ import org.eclipse.jetty.util.log.Logger;
  *
  * License information for Bjoern Hoehrmann's code:
  *
- * Copyright (c) 2008-2009 Bjoern Hoehrmann <bjoern@hoehrmann.de>
+ * Copyright (c) 2008-2009 Bjoern Hoehrmann &lt;bjoern@hoehrmann.de&gt;
  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal
  * in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedAttribute.java

@@ -25,14 +25,13 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * The @ManagedAttribute annotation is used to indicate that a given method 
+ * The <code>&#064;ManagedAttribute</code> annotation is used to indicate that a given method 
  * exposes a JMX attribute. This annotation is placed always on the reader 
  * method of a given attribute. Unless it is marked as read-only in the 
  * configuration of the annotation a corresponding setter is looked for 
  * following normal naming conventions. For example if this annotation is 
  * on a method called getFoo() then a method called setFoo() would be looked 
  * for and if found wired automatically into the jmx attribute.
- *
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
@@ -42,7 +41,7 @@ public @interface ManagedAttribute
     /**
      * Description of the Managed Attribute
      * 
-     * @returngit checkout
+     * @return value
      */
     String value() default "Not Specified";
     

jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedObject.java

@@ -25,12 +25,11 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * The @ManagedObject annotation is used on a class at the top level to 
+ * The <code>&#064;ManagedObject</code> annotation is used on a class at the top level to 
  * indicate that it should be exposed as an mbean. It has only one attribute 
  * to it which is used as the description of the MBean. Should multiple 
- * @ManagedObject annotations be found in the chain of influence then the 
+ * <code>&#064;ManagedObject</code> annotations be found in the chain of influence then the 
  * first description is used.
- *
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
@@ -39,6 +38,7 @@ public @interface ManagedObject
 {
     /**
      * Description of the Managed Object
+     * @return value
      */
     String value() default "Not Specified";
   

jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedOperation.java

@@ -25,9 +25,8 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * The @ManagedOperation annotation is used to indicate that a given method 
+ * The <code>&#064;ManagedOperation</code> annotation is used to indicate that a given method 
  * should be considered a JMX operation.
- *
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
@@ -36,6 +35,7 @@ public @interface ManagedOperation
 {
     /**
      * Description of the Managed Object
+     * @return value
      */
     String value() default "Not Specified";
     

jetty-util/src/main/java/org/eclipse/jetty/util/annotation/Name.java

@@ -39,11 +39,13 @@ public @interface Name
 {
     /**
      * the name of the parameter
+     * @return the value
      */
     String value();
     
     /**
      * the description of the parameter
+     * @return the description
      */
     String description() default "";
 }

jetty-util/src/main/java/org/eclipse/jetty/util/component/Container.java

@@ -20,6 +20,9 @@ package org.eclipse.jetty.util.component;
 
 import java.util.Collection;
 
+/**
+ * A Container
+ */
 public interface Container
 {
     /* ------------------------------------------------------------ */
@@ -39,6 +42,7 @@ public interface Container
     /**
      * @param clazz the class of the beans
      * @return the list of beans of the given class (or subclass)
+     * @param <T> the Bean type
      * @see #getBeans()
      */
     public <T> Collection<T> getBeans(Class<T> clazz);
@@ -46,12 +50,14 @@ public interface Container
     /**
      * @param clazz the class of the bean
      * @return the first bean of a specific class (or subclass), or null if no such bean exist
+     * @param <T> the Bean type 
      */
     public <T> T getBean(Class<T> clazz);
 
     /**
      * Removes the given bean.
      * If the bean is-a {@link Listener}, then also do an implicit {@link #removeEventListener(Listener)}.
+     * @param o the bean to remove
      * @return whether the bean was removed
      */
     public boolean removeBean(Object o);
@@ -59,14 +65,14 @@ public interface Container
     /**
      * Add an event listener. 
      * @see Container#addBean(Object)
-     * @param listener
+     * @param listener the listener to add
      */
     public void addEventListener(Listener listener);
     
     /**
      * Remove an event listener. 
      * @see Container#removeBean(Object)
-     * @param listener
+     * @param listener the listener to remove
      */
     public void removeEventListener(Listener listener);
 

jetty-util/src/main/java/org/eclipse/jetty/util/component/ContainerLifeCycle.java

@@ -124,8 +124,8 @@ public class ContainerLifeCycle extends AbstractLifeCycle implements Container,
     /**
      * Starts the given lifecycle.
      *
-     * @param l
+     * @param l the lifecycle to start
-     * @throws Exception
+     * @throws Exception if unable to start lifecycle
      */
     protected void start(LifeCycle l) throws Exception
     {
@@ -135,8 +135,8 @@ public class ContainerLifeCycle extends AbstractLifeCycle implements Container,
     /**
      * Stops the given lifecycle.
      *
-     * @param l
+     * @param l the lifecycle to stop
-     * @throws Exception
+     * @throws Exception if unable to stop the lifecycle
      */
     protected void stop(LifeCycle l) throws Exception
     {
@@ -329,11 +329,11 @@ public class ContainerLifeCycle extends AbstractLifeCycle implements Container,
     
     /* ------------------------------------------------------------ */
     /** Add a managed lifecycle.
-     * <p>This is a conveniance method that uses addBean(lifecycle,true)
+     * <p>This is a convenience method that uses addBean(lifecycle,true)
      * and then ensures that the added bean is started iff this container
      * is running.  Exception from nested calls to start are caught and 
      * wrapped as RuntimeExceptions
-     * @param lifecycle
+     * @param lifecycle the managed lifecycle to add
      */
     public void addManaged(LifeCycle lifecycle)
     {

jetty-util/src/main/java/org/eclipse/jetty/util/component/LifeCycle.java

@@ -26,7 +26,7 @@ import org.eclipse.jetty.util.annotation.ManagedOperation;
 /* ------------------------------------------------------------ */
 /**
  * The lifecycle interface for generic components.
- * <br />
+ * <br>
  * Classes implementing this interface have a defined life cycle
  * defined by the methods of this interface.
  *

jetty-util/src/main/java/org/eclipse/jetty/util/log/Logger.java

@@ -117,6 +117,7 @@ public interface Logger
     /**
      * Ignore an exception.
      * <p>This should be used rather than an empty catch block.
+     * @param ignored the throwable to log as ignored
      */
     public void ignore(Throwable ignored); 
 }

jetty-util/src/main/java/org/eclipse/jetty/util/log/StdErrLog.java

@@ -37,10 +37,10 @@ import org.eclipse.jetty.util.annotation.ManagedObject;
  * <dl>
  *   <dt>${name|hierarchy}.LEVEL=(ALL|DEBUG|INFO|WARN|OFF)</dt>
  *   <dd>
- *   Sets the level that the Logger should log at.<br/>
+ *   Sets the level that the Logger should log at.<br>
- *   Names can be a package name, or a fully qualified class name.<br/>
+ *   Names can be a package name, or a fully qualified class name.<br>
- *   Default: INFO<br/>
+ *   Default: INFO<br>
- *   <br/>
+ *   <br>
  *   Examples:
  *   <dl>
  *   <dt>org.eclipse.jetty.LEVEL=WARN</dt>
@@ -56,35 +56,35 @@ import org.eclipse.jetty.util.annotation.ManagedObject;
  *   <dt>${name}.SOURCE=(true|false)</dt>
  *   <dd>
  *   Logger specific, attempt to print the java source file name and line number
- *   where the logging event originated from.<br/>
+ *   where the logging event originated from.<br>
  *   Name must be a fully qualified class name (package name hierarchy is not supported
- *   by this configurable)<br/>
+ *   by this configurable)<br>
- *   Warning: this is a slow operation and will have an impact on performance!<br/>
+ *   Warning: this is a slow operation and will have an impact on performance!<br>
  *   Default: false
  *   </dd>
  *   
  *   <dt>${name}.STACKS=(true|false)</dt>
  *   <dd>
- *   Logger specific, control the display of stacktraces.<br/>
+ *   Logger specific, control the display of stacktraces.<br>
  *   Name must be a fully qualified class name (package name hierarchy is not supported
- *   by this configurable)<br/>
+ *   by this configurable)<br>
  *   Default: true
  *   </dd>
  *   
  *   <dt>org.eclipse.jetty.util.log.stderr.SOURCE=(true|false)</dt>
  *   <dd>Special Global Configuration, attempt to print the java source file name and line number
- *   where the logging event originated from.<br/>
+ *   where the logging event originated from.<br>
  *   Default: false
  *   </dd>
  *   
  *   <dt>org.eclipse.jetty.util.log.stderr.LONG=(true|false)</dt>
  *   <dd>Special Global Configuration, when true, output logging events to STDERR using
- *   long form, fully qualified class names.  when false, use abbreviated package names<br/>
+ *   long form, fully qualified class names.  when false, use abbreviated package names<br>
  *   Default: false
  *   </dd>
  *   <dt>org.eclipse.jetty.util.log.stderr.ESCAPE=(true|false)</dt>
  *   <dd>Global Configuration, when true output logging events to STDERR are always
- *   escaped so that control characters are replaced with '?";  '\r' with '<' and '\n' replaced '|'<br/>
+ *   escaped so that control characters are replaced with '?";  '\r' with '&lt;' and '\n' replaced '|'<br>
  *   Default: true
  *   </dd>
  * </dl>
@@ -339,7 +339,6 @@ public class StdErrLog extends AbstractLogger
     /**
      * Condenses a classname by stripping down the package name to just the first character of each package name
      * segment.Configured
-     * <p>
      *
      * <pre>
      * Examples:

jetty-util/src/main/java/org/eclipse/jetty/util/resource/FileResource.java

@@ -346,7 +346,7 @@ public class FileResource extends Resource
     
     /* ------------------------------------------------------------ */
     /** 
-     * @param o
+     * @param o the object to compare against this instance
      * @return <code>true</code> of the object <code>o</code> is a {@link FileResource} pointing to the same file as this resource. 
      */
     @Override

jetty-util/src/main/java/org/eclipse/jetty/util/resource/JarFileResource.java

@@ -381,7 +381,7 @@ class JarFileResource extends JarResource
     /**
      * Take a Resource that possibly might use URLConnection caching
      * and turn it into one that doesn't.
-     * @param resource
+     * @param resource the JarFileResource to obtain without URLConnection caching. 
      * @return the non-caching resource
      */
     public static Resource getNonCachingResource (Resource resource)
@@ -399,9 +399,9 @@ class JarFileResource extends JarResource
     /**
      * Check if this jar:file: resource is contained in the
      * named resource. Eg <code>jar:file:///a/b/c/foo.jar!/x.html</code> isContainedIn <code>file:///a/b/c/foo.jar</code>
-     * @param resource
+     * @param resource the resource to test for
      * @return true if resource is contained in the named resource
-     * @throws MalformedURLException
+     * @throws MalformedURLException if unable to process is contained due to invalid URL format
      */
     @Override
     public boolean isContainedIn (Resource resource) 

jetty-util/src/main/java/org/eclipse/jetty/util/resource/PathResource.java

@@ -89,11 +89,33 @@ public class PathResource extends Resource
         return null;
     }
 
+    /**
+     * Construct a new PathResource from a File object.
+     * <p>
+     * An invocation of this convenience constructor of the form.
+     * </p>
+     * <pre>
+     * new PathResource(file);
+     * </pre>
+     * <p>
+     * behaves in exactly the same way as the expression
+     * </p>
+     * <pre>
+     * new PathResource(file.toPath());
+     * </pre>
+
+     * @param file the file to use
+     */
     public PathResource(File file)
     {
         this(file.toPath());
     }
 
+    /**
+     * Construct a new PathResource from a Path object.
+     * 
+     * @param path the path to use
+     */
     public PathResource(Path path)
     {
         this.path = path.toAbsolutePath();
@@ -101,6 +123,14 @@ public class PathResource extends Resource
         this.alias = checkAliasPath(path);
     }
 
+    /**
+     * Construct a new PathResource from a URI object.
+     * <p>
+     * Must be an absolute URI using the <code>file</code> scheme.
+     * 
+     * @param uri the URI to build this PathResource from.
+     * @throws IOException if unable to construct the PathResource from the URI.
+     */
     public PathResource(URI uri) throws IOException
     {
         if (!uri.isAbsolute())
@@ -137,6 +167,25 @@ public class PathResource extends Resource
         this.alias = checkAliasPath(path);
     }
 
+    /**
+     * Create a new PathResource from a provided URL object.
+     * <p>
+     * An invocation of this convenience constructor of the form.
+     * </p>
+     * <pre>
+     * new PathResource(url);
+     * </pre>
+     * <p>
+     * behaves in exactly the same way as the expression
+     * </p>
+     * <pre>
+     * new PathResource(url.toURI());
+     * </pre>
+     * 
+     * @param url the url to attempt to create PathResource from
+     * @throws IOException if URL doesn't point to a location that can be transformed to a PathResource
+     * @throws URISyntaxException if the provided URL was malformed
+     */
     public PathResource(URL url) throws IOException, URISyntaxException
     {
         this(url.toURI());
@@ -225,7 +274,10 @@ public class PathResource extends Resource
         return path.toFile();
     }
 
-    public Path getPath() throws IOException
+    /**
+     * @return the {@link Path} of the resource
+     */
+    public Path getPath()
     {
         return path;
     }
@@ -324,6 +376,11 @@ public class PathResource extends Resource
         return this.alias!=null;
     }
     
+    /**
+     * The Alias as a Path.
+     * 
+     * @return the alias as a path.
+     */
     public Path getAliasPath()
     {
         return this.alias;

jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java

@@ -39,6 +39,7 @@ import org.eclipse.jetty.util.IO;
 import org.eclipse.jetty.util.Loader;
 import org.eclipse.jetty.util.StringUtil;
 import org.eclipse.jetty.util.URIUtil;
+import org.eclipse.jetty.util.UrlEncoded;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
@@ -61,7 +62,7 @@ public abstract class Resource implements ResourceFactory, Closeable
     /**
      * Change the default setting for url connection caches.
      * Subsequent URLConnections will use this default.
-     * @param useCaches
+     * @param useCaches true to enable URL connection caches, false otherwise.
      */
     public static void setDefaultUseCaches (boolean useCaches)
     {
@@ -257,6 +258,8 @@ public abstract class Resource implements ResourceFactory, Closeable
 
     /* ------------------------------------------------------------ */
     /** Find a classpath resource.
+     * @param resource the relative name of the resource
+     * @return Resource or null
      */
     public static Resource newClassPathResource(String resource)
     {
@@ -320,43 +323,52 @@ public abstract class Resource implements ResourceFactory, Closeable
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns true if the respresened resource exists.
+     * @return true if the represented resource exists.
      */
     public abstract boolean exists();
     
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns true if the respresenetd resource is a container/directory.
+     * @return true if the represented resource is a container/directory.
-     * If the resource is not a file, resources ending with "/" are
+     * if the resource is not a file, resources ending with "/" are
      * considered directories.
      */
     public abstract boolean isDirectory();
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns the last modified time
+     * Time resource was last modified.
+     * 
+     * @return the last modified time as milliseconds since unix epoch
      */
     public abstract long lastModified();
 
 
     /* ------------------------------------------------------------ */
     /**
-     * Return the length of the resource
+     * Length of the resource.
+     * 
+     * @return the length of the resource
      */
     public abstract long length();
     
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns an URL representing the given resource
+     * URL representing the resource.
+     * 
+     * @return an URL representing the given resource
+     * @deprecated use {{@link #getURI()}.toURL() instead.
      */
-    // TODO: should deprecate this one and only use getURI()
+    @Deprecated
     public abstract URL getURL();
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns an URI representing the given resource
+     * URI representing the resource.
+     * 
+     * @return an URI representing the given resource
      */
     public URI getURI()
     {
@@ -373,8 +385,11 @@ public abstract class Resource implements ResourceFactory, Closeable
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns an File representing the given resource or NULL if this
+     * File representing the given resource.
+     * 
+     * @return an File representing the given resource or NULL if this
      * is not possible.
+     * @throws IOException if unable to get the resource due to permissions 
      */
     public abstract File getFile()
         throws IOException;
@@ -382,47 +397,60 @@ public abstract class Resource implements ResourceFactory, Closeable
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns the name of the resource
+     * The name of the resource.
+     * 
+     * @return the name of the resource
      */
     public abstract String getName();
     
 
     /* ------------------------------------------------------------ */
     /**
-     * Returns an input stream to the resource
+     * Input stream to the resource
+     * 
+     * @return an input stream to the resource
+     * @throws IOException if unable to open the input stream
      */
     public abstract InputStream getInputStream()
-        throws java.io.IOException;
+        throws IOException;
     
     /* ------------------------------------------------------------ */
     /**
-     * Returns an readable bytechannel to the resource or null if one is not available.
+     * Readable ByteChannel for the resource.
+     * 
+     * @return an readable bytechannel to the resource or null if one is not available.
+     * @throws IOException if unable to open the readable bytechannel for the resource.
      */
     public abstract ReadableByteChannel getReadableByteChannel()
-        throws java.io.IOException;
+        throws IOException;
 
     /* ------------------------------------------------------------ */
     /**
      * Deletes the given resource
+     * @return true if resource was found and successfully deleted, false if resource didn't exist or was unable to
+     * be deleted.
+     * @throws SecurityException if unable to delete due to permissions 
      */
-    // TODO: can throw IOException
     public abstract boolean delete()
         throws SecurityException;
     
     /* ------------------------------------------------------------ */
     /**
      * Rename the given resource
+     * @param dest the destination name for the resource
+     * @return true if the resource was renamed, false if the resource didn't exist or was unable to be renamed.
+     * @throws SecurityException if unable to rename due to permissions
      */
-    // TODO: can throw IOException
+    public abstract boolean renameTo(Resource dest)
-    public abstract boolean renameTo( Resource dest)
         throws SecurityException;
     
     /* ------------------------------------------------------------ */
     /**
-     * Returns a list of resource names contained in the given resource
+     * list of resource names contained in the given resource.
-     * The resource names are not URL encoded.
+     * 
+     * @return a list of resource names contained in the given resource.
+     * Note: The resource names are not URL encoded.
      */
-    // TODO: can throw IOException
     public abstract String[] list();
 
     /* ------------------------------------------------------------ */
@@ -430,6 +458,9 @@ public abstract class Resource implements ResourceFactory, Closeable
      * Returns the resource contained inside the current resource with the
      * given name.
      * @param path The path segment to add, which is not encoded
+     * @return the Resource for the resolved path within this Resource.
+     * @throws IOException if unable to resolve the path
+     * @throws MalformedURLException if the resolution of the path fails because the input path parameter is malformed.
      */
     public abstract Resource addPath(String path)
         throws IOException,MalformedURLException;
@@ -457,26 +488,36 @@ public abstract class Resource implements ResourceFactory, Closeable
 
     /* ------------------------------------------------------------ */
     /** 
-     * @deprecated
+     * @param uri the uri to encode
+     * @return null (this is deprecated)
+     * @deprecated use {@link URIUtil} or {@link UrlEncoded} instead
      */
+    @Deprecated
     public String encode(String uri)
     {
         return null;
     }
         
     /* ------------------------------------------------------------ */
+    // FIXME: this appears to not be used
+    @SuppressWarnings("javadoc")
     public Object getAssociate()
     {
         return _associate;
     }
 
     /* ------------------------------------------------------------ */
+    // FIXME: this appear to not be used
+    @SuppressWarnings("javadoc")
     public void setAssociate(Object o)
     {
         _associate=o;
     }
 
     /* ------------------------------------------------------------ */
+    /**
+     * @return true if this Resource is an alias to another real Resource
+     */
     public boolean isAlias()
     {
         return getAlias()!=null;
@@ -496,6 +537,7 @@ public abstract class Resource implements ResourceFactory, Closeable
      * @param base The base URL
      * @param parent True if the parent directory should be included
      * @return String of HTML
+     * @throws IOException if unable to get the list of resources as HTML
      */
     public String getListHTML(String base,boolean parent)
         throws IOException
@@ -623,9 +665,10 @@ public abstract class Resource implements ResourceFactory, Closeable
     
     /* ------------------------------------------------------------ */
     /** 
-     * @param out 
+     * @param out the output stream to write to 
      * @param start First byte to write
      * @param count Bytes to write or -1 for all of them.
+     * @throws IOException if unable to copy the Resource to the output
      */
     public void writeTo(OutputStream out,long start,long count)
         throws IOException
@@ -641,11 +684,20 @@ public abstract class Resource implements ResourceFactory, Closeable
     }    
     
     /* ------------------------------------------------------------ */
+    /**
+     * Copy the Resource to the new destination file.
+     * <p>
+     * Will not replace existing destination file.
+     * 
+     * @param destination the destination file to create
+     * @throws IOException if unable to copy the resource
+     */
     public void copyTo(File destination)
         throws IOException
     {
         if (destination.exists())
-            throw new IllegalArgumentException(destination+" exists");
+            throw new IllegalArgumentException(destination + " exists");
+        
         try (OutputStream out = new FileOutputStream(destination))
         {
             writeTo(out,0,-1);
@@ -653,6 +705,11 @@ public abstract class Resource implements ResourceFactory, Closeable
     }
 
     /* ------------------------------------------------------------ */
+    /**
+     * Generate a weak ETag reference for this Resource.
+     * 
+     * @return the weak ETag reference for this resource.
+     */
     public String getWeakETag()
     {
         try
@@ -709,7 +766,7 @@ public abstract class Resource implements ResourceFactory, Closeable
     /** Generate a properly encoded URL from a {@link File} instance.
      * @param file Target file. 
      * @return URL of the target file.
-     * @throws MalformedURLException 
+     * @throws MalformedURLException if unable to convert File to URL
      */
     public static URL toURL(File file) throws MalformedURLException
     {

jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceCollection.java

@@ -248,10 +248,10 @@ public class ResourceCollection extends Resource
     
     /* ------------------------------------------------------------ */
     /**
-     * @param path
+     * @param path the path to look for
      * @return the resource(file) if found, returns a list of resource dirs if its a dir, else null.
-     * @throws IOException
+     * @throws IOException if unable to look for path
-     * @throws MalformedURLException
+     * @throws MalformedURLException if failed to look for path due to url issue
      */
     protected Object findResource(String path) throws IOException, MalformedURLException
     {        

jetty-util/src/main/java/org/eclipse/jetty/util/resource/URLResource.java

@@ -221,9 +221,11 @@ public class URLResource extends Resource
      * the url protocol. Eg JarURLConnection does not reuse inputstreams.
      * 
      * @param resetConnection if true the connection field is set to null
+     * @return the inputstream for this resource
+     * @throws IOException if unable to open the input stream
      */
     protected synchronized InputStream getInputStream(boolean resetConnection)
-        throws java.io.IOException
+        throws IOException
     {
         if (!checkConnection())
             throw new IOException( "Invalid resource");

jetty-util/src/main/java/org/eclipse/jetty/util/security/CertificateValidator.java

@@ -72,8 +72,8 @@ public class CertificateValidator
     /**
      * creates an instance of the certificate validator 
      *
-     * @param trustStore 
+     * @param trustStore the truststore to use 
-     * @param crls
+     * @param crls the Certificate Revocation List to use 
      */
     public CertificateValidator(KeyStore trustStore, Collection<? extends CRL> crls)
     {
@@ -89,8 +89,8 @@ public class CertificateValidator
     /**
      * validates all aliases inside of a given keystore
      * 
-     * @param keyStore
+     * @param keyStore the keystore to validate
-     * @throws CertificateException
+     * @throws CertificateException if keystore error and unable to validate 
      */
     public void validate( KeyStore keyStore ) throws CertificateException
     {
@@ -116,10 +116,10 @@ public class CertificateValidator
     /**
      * validates a specific alias inside of the keystore being passed in
      * 
-     * @param keyStore
+     * @param keyStore the keystore to validate
-     * @param keyAlias
+     * @param keyAlias the keyalias in the keystore to valid with
      * @return the keyAlias if valid
-     * @throws CertificateException
+     * @throws CertificateException if keystore error and unable to validate
      */
     public String validate(KeyStore keyStore, String keyAlias) throws CertificateException
     {
@@ -146,9 +146,9 @@ public class CertificateValidator
     /**
      * validates a specific certificate inside of the keystore being passed in
      * 
-     * @param keyStore
+     * @param keyStore the keystore to validate against
-     * @param cert
+     * @param cert the certificate to validate
-     * @throws CertificateException
+     * @throws CertificateException if keystore error and unable to validate
      */
     public void validate(KeyStore keyStore, Certificate cert) throws CertificateException
     {

jetty-util/src/main/java/org/eclipse/jetty/util/security/Constraint.java

@@ -21,13 +21,10 @@ package org.eclipse.jetty.util.security;
 import java.io.Serializable;
 import java.util.Arrays;
 
-/* ------------------------------------------------------------ */
 /**
  * Constraint
  * 
  * Describe an auth and/or data constraint.
- * 
- * 
  */
 public class Constraint implements Cloneable, Serializable
 {
@@ -93,10 +90,10 @@ public class Constraint implements Cloneable, Serializable
 
     /* ------------------------------------------------------------ */
     /**
-     * Conveniance Constructor.
+     * Convenience Constructor.
      * 
-     * @param name
+     * @param name the name
-     * @param role
+     * @param role the role
      */
     public Constraint(String name, String role)
     {
@@ -113,7 +110,7 @@ public class Constraint implements Cloneable, Serializable
 
     /* ------------------------------------------------------------ */
     /**
-     * @param name
+     * @param name the name
      */
     public void setName(String name)
     {
@@ -172,7 +169,7 @@ public class Constraint implements Cloneable, Serializable
 
     /* ------------------------------------------------------------ */
     /**
-     * @param role
+     * @param role the role
      * @return True if the constraint contains the role.
      */
     public boolean hasRole(String role)
@@ -212,7 +209,7 @@ public class Constraint implements Cloneable, Serializable
 
     /* ------------------------------------------------------------ */
     /**
-     * @param c Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
+     * @param c Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
      *                2=DC_CONFIDENTIAL
      */
     public void setDataConstraint(int c)
@@ -223,7 +220,7 @@ public class Constraint implements Cloneable, Serializable
 
     /* ------------------------------------------------------------ */
     /**
-     * @return Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
+     * @return Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
      *         2=DC_CONFIDENTIAL
      */
     public int getDataConstraint()

jetty-util/src/main/java/org/eclipse/jetty/util/security/Password.java

@@ -245,10 +245,6 @@ public class Password extends Credential
         return new Password(passwd);
     }
 
-    /* ------------------------------------------------------------ */
-    /**
-     * @param arg
-     */
     public static void main(String[] arg)
     {
         if (arg.length != 1 && arg.length != 2)

jetty-util/src/main/java/org/eclipse/jetty/util/ssl/AliasedX509ExtendedKeyManager.java

@@ -43,7 +43,7 @@ public class AliasedX509ExtendedKeyManager extends X509ExtendedKeyManager
      * Construct KeyManager instance
      * @param keyAlias Alias of the key to be selected
      * @param keyManager Instance of KeyManager to be wrapped
-     * @throws Exception
+     * @throws Exception if unable to create X509ExtendedKeyManager
      */
     public AliasedX509ExtendedKeyManager(X509ExtendedKeyManager keyManager, String keyAlias) throws Exception
     {

jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SniX509ExtendedKeyManager.java

@@ -48,8 +48,8 @@ public class SniX509ExtendedKeyManager extends X509ExtendedKeyManager
     /**
      * Construct KeyManager instance
      * @param keyManager Instance of KeyManager to be wrapped
-     * @param dftAlias Alias of the key to be selected if no SNI selection
+     * @param alias Alias of the key to be selected if no SNI selection
-     * @throws Exception
+     * @throws Exception if unable to create X509ExtendedKeyManager
      */
     public SniX509ExtendedKeyManager(X509ExtendedKeyManager keyManager,String alias) throws Exception
     {

jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java

@@ -642,7 +642,7 @@ public class SslContextFactory extends AbstractLifeCycle
     /**
      * @param password
      *            The password for the key store.  If null is passed then 
-     *            the {@link Password#getPassword(String, String, String) is used to
+     *            the {@link Password#getPassword(String, String, String)} is used to
      *            obtain a password either from the "org.eclipse.jetty.ssl.password"
      *            System property or by prompting for manual entry.
      */
@@ -659,7 +659,7 @@ public class SslContextFactory extends AbstractLifeCycle
      * @param password
      *            The password (if any) for the specific key within the key store.
      *            If null is passed then 
-     *            the {@link Password#getPassword(String, String, String) is used to
+     *            the {@link Password#getPassword(String, String, String)} is used to
      *            obtain a password either from the "org.eclipse.jetty.ssl.keypassword"
      *            System property or by prompting for manual entry.
      */
@@ -674,7 +674,7 @@ public class SslContextFactory extends AbstractLifeCycle
     /**
      * @param password
      *            The password for the trust store. If null is passed then 
-     *            the {@link Password#getPassword(String, String, String) is used to
+     *            the {@link Password#getPassword(String, String, String)} is used to
      *            obtain a password either from the "org.eclipse.jetty.ssl.password"
      *            System property or by prompting for manual entry.
      */
@@ -888,6 +888,7 @@ public class SslContextFactory extends AbstractLifeCycle
     /**
      * Override this method to provide alternate way to load a keystore.
      * 
+     * @param resource the resource to load the keystore from 
      * @return the key store instance
      * @throws Exception if the keystore cannot be loaded
      */
@@ -899,6 +900,7 @@ public class SslContextFactory extends AbstractLifeCycle
     /**
      * Override this method to provide alternate way to load a truststore.
      * 
+     * @param resource the resource to load the truststore from 
      * @return the key store instance
      * @throws Exception if the truststore cannot be loaded
      */
@@ -1317,7 +1319,7 @@ public class SslContextFactory extends AbstractLifeCycle
     /**
      * Factory method for "scratch" {@link SSLEngine}s, usually only used for retrieving configuration
      * information such as the application buffer size or the list of protocols/ciphers.
-     * <p />
+     * <p>
      * This method should not be used for creating {@link SSLEngine}s that are used in actual socket
      * communication.
      *
@@ -1351,17 +1353,17 @@ public class SslContextFactory extends AbstractLifeCycle
 
     /**
      * Server-side only factory method for creating {@link SSLEngine}s.
-     * <p />
+     * <p>
      * If the given {@code address} is null, it is equivalent to {@link #newSSLEngine()}, otherwise
      * {@link #newSSLEngine(String, int)} is called.
-     * <p />
+     * <p>
      * If {@link #getNeedClientAuth()} is {@code true}, then the host name is passed to
      * {@link #newSSLEngine(String, int)}, possibly incurring in a reverse DNS lookup, which takes time
      * and may hang the selector (since this method is usually called by the selector thread).
-     * <p />
+     * <p>
      * Otherwise, the host address is passed to {@link #newSSLEngine(String, int)} without DNS lookup
      * penalties.
-     * <p />
+     * <p>
      * Clients that wish to create {@link SSLEngine} instances must use {@link #newSSLEngine(String, int)}.
      *
      * @param address the remote peer address

jetty-util/src/main/java/org/eclipse/jetty/util/statistic/CounterStatistic.java

@@ -54,6 +54,7 @@ public class CounterStatistic
     /* ------------------------------------------------------------ */
     /**
      * @param delta the amount to add to the count
+     * @return the new value
      */
     public long add(final long delta)
     {
@@ -68,6 +69,8 @@ public class CounterStatistic
 
     /* ------------------------------------------------------------ */
     /**
+     * increment the value by one
+     * @return the new value, post increment
      */
     public long increment()
     {
@@ -76,6 +79,8 @@ public class CounterStatistic
 
     /* ------------------------------------------------------------ */
     /**
+     * decrement by 1
+     * @return the new value, post-decrement
      */
     public long decrement()
     {

jetty-util/src/main/java/org/eclipse/jetty/util/statistic/SampleStatistic.java

@@ -23,23 +23,20 @@ import java.util.concurrent.atomic.AtomicLong;
 import org.eclipse.jetty.util.Atomics;
 
 
-/* ------------------------------------------------------------ */
 /**
  * SampledStatistics
  * <p>
- * Provides max, total, mean, count, variance, and standard
+ * Provides max, total, mean, count, variance, and standard deviation of continuous sequence of samples.
- * deviation of continuous sequence of samples.
  * <p>
- * Calculates estimates of mean, variance, and standard deviation
+ * Calculates estimates of mean, variance, and standard deviation characteristics of a sample using a non synchronized
- * characteristics of a sample using a non synchronized
+ * approximation of the on-line algorithm presented in <cite>Donald Knuth's Art of Computer Programming, Volume 2,
- * approximation of the on-line algorithm presented
+ * Seminumerical Algorithms, 3rd edition, page 232, Boston: Addison-Wesley</cite>. that cites a 1962 paper by B.P. Welford that
- * in Donald Knuth's Art of Computer Programming, Volume 2,
+ * can be found by following <a href="http://www.jstor.org/pss/1266577">Note on a Method for Calculating Corrected Sums
- * Seminumerical Algorithms, 3rd edition, page 232,
+ * of Squares and Products</a>
- * Boston: Addison-Wesley. that cites a 1962 paper by B.P. Welford
- * that can be found by following the link http://www.jstor.org/pss/1266577
  * <p>
- * This algorithm is also described in Wikipedia at
+ * This algorithm is also described in Wikipedia at <a href=
- * http://en.wikipedia.org/w/index.php?title=Algorithms_for_calculating_variance&section=4#On-line_algorithm
+ * "http://en.wikipedia.org/w/index.php?title=Algorithms_for_calculating_variance&amp;section=4#On-line_algorithm">
+ * Algorithms for calculating variance </a>
  */
 public class SampleStatistic
 {

jetty-util/src/main/java/org/eclipse/jetty/util/thread/ExecutorThreadPool.java

@@ -65,7 +65,7 @@ public class ExecutorThreadPool extends AbstractLifeCycle implements ThreadPool,
     /* ------------------------------------------------------------ */
     /**
      * Wraps an {@link ThreadPoolExecutor}.
-     * Max pool size is 256, pool thread timeout after 60 seconds, and core pool size is 32 when queueSize >= 0.
+     * Max pool size is 256, pool thread timeout after 60 seconds, and core pool size is 32 when queueSize >= 0.
      * @param queueSize can be -1 for using an unbounded {@link LinkedBlockingQueue}, 0 for using a
      * {@link SynchronousQueue}, greater than 0 for using a {@link ArrayBlockingQueue} of the given size.
      */

jetty-util/src/main/java/org/eclipse/jetty/util/thread/QueuedThreadPool.java

@@ -193,7 +193,10 @@ public class QueuedThreadPool extends AbstractLifeCycle implements SizedThreadPo
     }
 
     /**
-     * Delegated to the named or anonymous Pool.
+     * Thread Pool should use Daemon Threading. 
+     *
+     * @param daemon true to enable delegation
+     * @see Thread#setDaemon(boolean)
      */
     public void setDaemon(boolean daemon)
     {
@@ -342,7 +345,10 @@ public class QueuedThreadPool extends AbstractLifeCycle implements SizedThreadPo
     }
 
     /**
-     * Delegated to the named or anonymous Pool.
+     * Is thread pool using daemon threading
+     * 
+     * @return true if delegating to named or anonymous pool
+     * @see Thread#setDaemon(boolean)
      */
     @ManagedAttribute("thead pool using a daemon thread")
     public boolean isDaemon()

jetty-util/src/main/java/org/eclipse/jetty/util/thread/ScheduledExecutorScheduler.java

@@ -32,7 +32,7 @@ import org.eclipse.jetty.util.component.Dumpable;
 
 /**
  * Implementation of {@link Scheduler} based on JDK's {@link ScheduledThreadPoolExecutor}.
- * <p />
+ * <p>
  * While use of {@link ScheduledThreadPoolExecutor} creates futures that will not be used,
  * it has the advantage of allowing to set a property to remove cancelled tasks from its
  * queue even if the task did not fire, which provides a huge benefit in the performance

jetty-util/src/main/java/org/eclipse/jetty/util/thread/ThreadPool.java

@@ -37,6 +37,7 @@ public interface ThreadPool extends Executor
     /* ------------------------------------------------------------ */
     /**
      * Blocks until the thread pool is {@link LifeCycle#stop stopped}.
+     * @throws InterruptedException if thread was interrupted
      */
     public void join() throws InterruptedException;
 

jetty-util/src/test/java/org/eclipse/jetty/util/log/StdErrLogTest.java

@@ -160,6 +160,7 @@ public class StdErrLogTest
 
     /**
      * Test to make sure that using a Null parameter on parameterized messages does not result in a NPE
+     * @throws NullPointerException failed test
      */
     @Test
     public void testParameterizedMessage_NullValues() throws NullPointerException
@@ -306,6 +307,7 @@ public class StdErrLogTest
      * Tests StdErrLog.warn() methods with level filtering.
      * <p>
      * Should always see WARN level messages, regardless of set level.
+     * @throws UnsupportedEncodingException failed test
      */
     @Test
     public void testWarnFiltering() throws UnsupportedEncodingException
@@ -345,6 +347,7 @@ public class StdErrLogTest
      * Tests StdErrLog.info() methods with level filtering.
      * <p>
      * Should only see INFO level messages when level is set to {@link StdErrLog#LEVEL_INFO} and below.
+     * @throws UnsupportedEncodingException failed test
      */
     @Test
     public void testInfoFiltering() throws UnsupportedEncodingException
@@ -390,6 +393,7 @@ public class StdErrLogTest
 
     /**
      * Tests {@link StdErrLog#LEVEL_OFF} filtering.
+     * @throws UnsupportedEncodingException failed test
      */
     @Test
     public void testOffFiltering() throws UnsupportedEncodingException
@@ -417,6 +421,7 @@ public class StdErrLogTest
      * Tests StdErrLog.debug() methods with level filtering.
      * <p>
      * Should only see DEBUG level messages when level is set to {@link StdErrLog#LEVEL_DEBUG} and below.
+     * @throws UnsupportedEncodingException failed test
      */
     @Test
     public void testDebugFiltering() throws UnsupportedEncodingException
@@ -465,6 +470,7 @@ public class StdErrLogTest
      * Tests StdErrLog with {@link Logger#ignore(Throwable)} use.
      * <p>
      * Should only see IGNORED level messages when level is set to {@link StdErrLog#LEVEL_ALL}.
+     * @throws UnsupportedEncodingException failed test
      */
     @Test
     public void testIgnores() throws UnsupportedEncodingException

jetty-util/src/test/java/org/eclipse/jetty/util/resource/ClassPathResourceTest.java

@@ -65,6 +65,7 @@ public class ClassPathResourceTest
 
     /**
      * Test a class path resource for directories.
+     * @throws Exception failed test
      */
     @Test
     public void testClassPathResourceDirectory() throws Exception
@@ -84,6 +85,7 @@ public class ClassPathResourceTest
 
     /**
      * Test a class path resource for a file.
+     * @throws Exception failed test
      */
     @Test
     public void testClassPathResourceFile() throws Exception

jetty-util/src/test/java/org/eclipse/jetty/util/resource/FileSystemResourceTest.java

@@ -583,6 +583,7 @@ public class FileSystemResourceTest
      * for long filenames.
      * <p>
      * See: http://support.microsoft.com/kb/142982
+     * @throws Exception failed test
      */
     @Test
     public void testCase8dot3Alias() throws Exception
@@ -617,6 +618,7 @@ public class FileSystemResourceTest
      * NTFS Alternative Data / File Streams.
      * <p>
      * See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
+     * @throws Exception failed test
      */
     @Test
     public void testNTFSFileStreamAlias() throws Exception
@@ -657,6 +659,7 @@ public class FileSystemResourceTest
      * NTFS Alternative Data / File Streams.
      * <p>
      * See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
+     * @throws Exception failed test
      */
     @Test
     public void testNTFSFileDataStreamAlias() throws Exception
@@ -699,6 +702,7 @@ public class FileSystemResourceTest
      * NTFS Alternative Data / File Streams.
      * <p>
      * See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
+     * @throws Exception failed test
      */
     @Test
     public void testNTFSFileEncodedDataStreamAlias() throws Exception
@@ -924,6 +928,7 @@ public class FileSystemResourceTest
 
     /**
      * The most basic access example
+     * @throws Exception failed test
      */
     @Test
     public void testExist_Normal() throws Exception