464727 - Update Javadoc for Java 8 DocLint

+ Fixing javadoc in jetty-http

jetty-http/src/main/java/org/eclipse/jetty/http/DateGenerator.java

@@ -26,7 +26,6 @@ import org.eclipse.jetty.util.StringUtil;
 
 /**
  * ThreadLocal Date formatters for HTTP style dates.
- *
  */
 public class DateGenerator
 {
@@ -56,6 +55,8 @@ public class DateGenerator
     
     /**
      * Format HTTP date "EEE, dd MMM yyyy HH:mm:ss 'GMT'"
+     * @param date the date in milliseconds
+     * @return the formatted date
      */
     public static String formatDate(long date)
     {
@@ -64,6 +65,8 @@ public class DateGenerator
 
     /**
      * Format "EEE, dd-MMM-yyyy HH:mm:ss 'GMT'" for cookies
+     * @param buf the buffer to put the formatted date into
+     * @param date the date in milliseconds
      */
     public static void formatCookieDate(StringBuilder buf, long date)
     {
@@ -72,6 +75,8 @@ public class DateGenerator
 
     /**
      * Format "EEE, dd-MMM-yyyy HH:mm:ss 'GMT'" for cookies
+     * @param date the date in milliseconds 
+     * @return the formatted date
      */
     public static String formatCookieDate(long date)
     {
@@ -85,6 +90,8 @@ public class DateGenerator
 
     /**
      * Format HTTP date "EEE, dd MMM yyyy HH:mm:ss 'GMT'"
+     * @param date the date in milliseconds
+     * @return the formatted date
      */
     public String doFormatDate(long date)
     {
@@ -125,6 +132,8 @@ public class DateGenerator
 
     /**
      * Format "EEE, dd-MMM-yy HH:mm:ss 'GMT'" for cookies
+     * @param buf the buffer to format the date into
+     * @param date the date in milliseconds
      */
     public void doFormatCookieDate(StringBuilder buf, long date)
     {

jetty-http/src/main/java/org/eclipse/jetty/http/HttpFields.java

@@ -57,13 +57,18 @@ public class HttpFields implements Iterable<HttpField>
     private HttpField[] _fields;
     private int _size;
     
+    /**
+     * Initialize an empty HttpFields.
+     */
     public HttpFields()
     {
         _fields=new HttpField[20];
     }
     
     /**
-     * Constructor.
+     * Initialize an empty HttpFields.
+     * 
+     * @param capacity the capacity of the http fields
      */
     public HttpFields(int capacity)
     {
@@ -71,7 +76,9 @@ public class HttpFields implements Iterable<HttpField>
     }
     
     /**
-     * Constructor.
+     * Initialize HttpFields from copy.
+     * 
+     * @param fields the fields to copy data from
      */
     public HttpFields(HttpFields fields)
     {
@@ -92,6 +99,7 @@ public class HttpFields implements Iterable<HttpField>
 
     /**
      * Get Collection of header names.
+     * @return the unique set of field names.
      */
     public Set<String> getFieldNamesCollection()
     {
@@ -107,6 +115,7 @@ public class HttpFields implements Iterable<HttpField>
     /**
      * Get enumeration of header _names. Returns an enumeration of strings representing the header
      * _names for this request.
+     * @return an enumeration of field names
      */
     public Enumeration<String> getFieldNames()
     {
@@ -115,14 +124,14 @@ public class HttpFields implements Iterable<HttpField>
 
     /**
      * Get a Field by index.
+     * @param index the field index 
      * @return A Field value or null if the Field value has not been set
-     *
      */
-    public HttpField getField(int i)
+    public HttpField getField(int index)
     {
-        if (i>=_size)
+        if (index>=_size)
             throw new NoSuchElementException();
-        return _fields[i];
+        return _fields[index];
     }
 
     public HttpField getField(HttpHeader header)
@@ -452,7 +461,7 @@ public class HttpFields implements Iterable<HttpField>
      *
      * @param header the header
      * @param value the value of the field.
-     * @exception IllegalArgumentException 
+     * @exception IllegalArgumentException if value is null
      */
     public void add(HttpHeader header, String value) throws IllegalArgumentException
     {
@@ -466,6 +475,7 @@ public class HttpFields implements Iterable<HttpField>
      * Remove a field.
      *
      * @param name the field to remove
+     * @return the header that was removed
      */
     public HttpField remove(HttpHeader name)
     {
@@ -486,6 +496,7 @@ public class HttpFields implements Iterable<HttpField>
      * Remove a field.
      *
      * @param name the field to remove
+     * @return the header that was removed
      */
     public HttpField remove(String name)
     {
@@ -507,6 +518,7 @@ public class HttpFields implements Iterable<HttpField>
      * case of the field name is ignored.
      *
      * @param name the case-insensitive field name
+     * @return the value of the field as a long
      * @exception NumberFormatException If bad long found
      */
     public long getLongField(String name) throws NumberFormatException
@@ -520,6 +532,7 @@ public class HttpFields implements Iterable<HttpField>
      * of the field name is ignored.
      *
      * @param name the case-insensitive field name
+     * @return the value of the field as a number of milliseconds since unix epoch
      */
     public long getDateField(String name)
     {

jetty-http/src/main/java/org/eclipse/jetty/http/HttpGenerator.java

@@ -29,15 +29,13 @@ import org.eclipse.jetty.util.StringUtil;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-/* ------------------------------------------------------------ */
 /**
  * HttpGenerator. Builds HTTP Messages.
- *
+ * <p>
  * If the system property "org.eclipse.jetty.http.HttpGenerator.STRICT" is set to true,
  * then the generator will strictly pass on the exact strings received from methods and header
  * fields.  Otherwise a fast case insensitive string lookup is used that may alter the
  * case and white space of some methods/headers
- * </p>
  */
 public class HttpGenerator
 {

jetty-http/src/main/java/org/eclipse/jetty/http/HttpParser.java

@@ -79,7 +79,7 @@ import org.eclipse.jetty.util.log.Logger;
  * case of the method and/or headers
  * </p>
  * <p>
- * @see http://tools.ietf.org/html/rfc7230
+ * @see <a href="http://tools.ietf.org/html/rfc7230">RFC 7230</a>
  */
 public class HttpParser
 {
@@ -275,7 +275,7 @@ public class HttpParser
 
     /* ------------------------------------------------------------ */
     /** Set if a HEAD response is expected
-     * @param head
+     * @param head true if head response is expected
      */
     public void setHeadResponse(boolean head)
     {
@@ -1153,6 +1153,7 @@ public class HttpParser
     /* ------------------------------------------------------------------------------- */
     /**
      * Parse until next Event.
+     * @param buffer the buffer to parse
      * @return True if an {@link RequestHandler} method was called and it returned true;
      */
     public boolean parseNext(ByteBuffer buffer)
@@ -1619,7 +1620,7 @@ public class HttpParser
          * This is the method called by parser when the HTTP request line is parsed
          * @param method The method 
          * @param uri The raw bytes of the URI.  These are copied into a ByteBuffer that will not be changed until this parser is reset and reused.
-         * @param version
+         * @param version the http version in use
          * @return true if handling parsing should return.
          */
         public boolean startRequest(String method, String uri, HttpVersion version);
@@ -1633,6 +1634,10 @@ public class HttpParser
     {
         /**
          * This is the method called by parser when the HTTP request line is parsed
+         * @param version the http version in use
+         * @param status the response status
+         * @param reason the response reason phrase
+         * @return true if handling parsing should return
          */
         public boolean startResponse(HttpVersion version, int status, String reason);
     }

jetty-http/src/main/java/org/eclipse/jetty/http/HttpStatus.java

@@ -25,6 +25,7 @@ package org.eclipse.jetty.http;
  * </p>
  *
  * <table border="1" cellpadding="5">
+ * <caption>HTTP Status Codes Table</caption>
  * <tr>
  * <th>Enum</th>
  * <th>Code</th>
@@ -155,8 +156,8 @@ package org.eclipse.jetty.http;
  * </tr>
  * <tr>
  * <td>&nbsp;</td>
- * <td><strike>207</strike></td>
- * <td><strike>Partial Update OK</strike></td>
+ * <td style="text-decoration: line-through;">207</td>
+ * <td style="text-decoration: line-through;">Partial Update OK</td>
  * <td>&nbsp;</td>
  * <td>
  * <a href=
@@ -448,8 +449,8 @@ package org.eclipse.jetty.http;
  * </tr>
  * <tr>
  * <td>&nbsp;</td>
- * <td><strike>418</strike></td>
- * <td><strike>Reauthentication Required</strike></td>
+ * <td style="text-decoration: line-through;">418</td>
+ * <td style="text-decoration: line-through;">Reauthentication Required</td>
  * <td>&nbsp;</td>
  * <td>
  * <a href=
@@ -459,8 +460,8 @@ package org.eclipse.jetty.http;
  * </tr>
  * <tr>
  * <td>&nbsp;</td>
- * <td><strike>418</strike></td>
- * <td><strike>Unprocessable Entity</strike></td>
+ * <td style="text-decoration: line-through;">418</td>
+ * <td style="text-decoration: line-through;">Unprocessable Entity</td>
  * <td>&nbsp;</td>
  * <td>&nbsp;</td>
  * <td>
@@ -470,8 +471,8 @@ package org.eclipse.jetty.http;
  * </tr>
  * <tr>
  * <td>&nbsp;</td>
- * <td><strike>419</strike></td>
- * <td><strike>Proxy Reauthentication Required</stike></td>
+ * <td style="text-decoration: line-through;">419</td>
+ * <td style="text-decoration: line-through;">Proxy Reauthentication Required</td>
  * <td>&nbsp;</td>
  * <td>
  * <a href=
@@ -481,8 +482,8 @@ package org.eclipse.jetty.http;
  * </tr>
  * <tr>
  * <td>&nbsp;</td>
- * <td><strike>419</strike></td>
- * <td><strike>Insufficient Space on Resource</stike></td>
+ * <td style="text-decoration: line-through;">419</td>
+ * <td style="text-decoration: line-through;">Insufficient Space on Resource</td>
  * <td>&nbsp;</td>
  * <td>&nbsp;</td>
  * <td>
@@ -492,8 +493,8 @@ package org.eclipse.jetty.http;
  * </tr>
  * <tr>
  * <td>&nbsp;</td>
- * <td><strike>420</strike></td>
- * <td><strike>Method Failure</strike></td>
+ * <td style="text-decoration: line-through;">420</td>
+ * <td style="text-decoration: line-through;">Method Failure</td>
  * <td>&nbsp;</td>
  * <td>&nbsp;</td>
  * <td>

jetty-http/src/main/java/org/eclipse/jetty/http/HttpURI.java

@@ -79,6 +79,14 @@ public class HttpURI
     /**
      * Construct a normalized URI.
      * Port is not set if it is the default port.
+     * @param scheme the URI scheme
+     * @param host the URI hose
+     * @param port the URI port
+     * @param path the URI path
+     * @param param the URI param
+     * @param query the URI query
+     * @param fragment the URI fragment
+     * @return the normalized URI
      */
     public static HttpURI createHttpURI(String scheme, String host, int port, String path, String param, String query, String fragment)
     {
@@ -671,8 +679,8 @@ public class HttpURI
     
     /* ------------------------------------------------------------ */
     /**
-     * @param host
-     * @param port
+     * @param host the host
+     * @param port the port
      */
     public void setAuthority(String host, int port)
     {
@@ -683,7 +691,7 @@ public class HttpURI
 
     /* ------------------------------------------------------------ */
     /**
-     * @param path
+     * @param path the path
      */
     public void setPath(String path)
     {

jetty-http/src/main/java/org/eclipse/jetty/http/MimeTypes.java

@@ -303,8 +303,8 @@ public class MimeTypes
 
     /* ------------------------------------------------------------ */
     /** Set a mime mapping
-     * @param extension
-     * @param type
+     * @param extension the extension
+     * @param type the mime type
      */
     public void addMimeMapping(String extension,String type)
     {

jetty-http/src/main/java/org/eclipse/jetty/http/PathMap.java

@@ -29,37 +29,46 @@ import org.eclipse.jetty.util.ArrayTernaryTrie;
 import org.eclipse.jetty.util.Trie;
 import org.eclipse.jetty.util.URIUtil;
 
-/* ------------------------------------------------------------ */
-/** URI path map to Object.
+/** 
+ * URI path map to Object.
+ * <p>
  * This mapping implements the path specification recommended
  * in the 2.2 Servlet API.
+ * </p>
  *
- * Path specifications can be of the following forms:<PRE>
+ * <p>
+ * Path specifications can be of the following forms:
+ * </p>
+ * <pre>
  * /foo/bar           - an exact path specification.
  * /foo/*             - a prefix path specification (must end '/*').
  * *.ext              - a suffix path specification.
  * /                  - the default path specification.
  * ""                 - the / path specification
- * </PRE>
- * Matching is performed in the following order <NL>
- * <LI>Exact match.
- * <LI>Longest prefix match.
- * <LI>Longest suffix match.
- * <LI>default.
- * </NL>
+ * </pre>
+ * 
+ * Matching is performed in the following order 
+ * <ol>
+ * <li>Exact match.</li>
+ * <li>Longest prefix match.</li>
+ * <li>Longest suffix match.</li>
+ * <li>default.</li>
+ * </ol>
+ * 
+ * <p>
  * Multiple path specifications can be mapped by providing a list of
  * specifications. By default this class uses characters ":," as path
  * separators, unless configured differently by calling the static
  * method @see PathMap#setPathSpecSeparators(String)
- * <P>
+ * <p>
  * Special characters within paths such as '?<EFBFBD> and ';' are not treated specially
  * as it is assumed they would have been either encoded in the original URL or
  * stripped from the path.
- * <P>
+ * <p>
  * This class is not synchronized.  If concurrent modifications are
  * possible then it should be synchronized at a higher level.
- *
- *
+ * 
+ * @param <O> the Map.Entry value type 
  */
 public class PathMap<O> extends HashMap<String,O>
 {
@@ -114,11 +123,13 @@ public class PathMap<O> extends HashMap<String,O>
     }
 
     /* --------------------------------------------------------------- */
-    /** Construct from dictionary PathMap.
+    /** 
+     * Construct from dictionary PathMap.
+     * @param dictMap the map representing the dictionary to build this PathMap from
      */
-    public PathMap(Map<String, ? extends O> m)
+    public PathMap(Map<String, ? extends O> dictMap)
     {
-        putAll(m);
+        putAll(dictMap);
     }
 
     /* --------------------------------------------------------------- */
@@ -382,7 +393,10 @@ public class PathMap<O> extends HashMap<String,O>
 
     /* --------------------------------------------------------------- */
     /**
+     * @param pathSpec the path spec
+     * @param path the path
      * @return true if match.
+     * @throws IllegalArgumentException if the matcher experienced a failure
      */
     public static boolean match(String pathSpec, String path)
         throws IllegalArgumentException
@@ -392,7 +406,11 @@ public class PathMap<O> extends HashMap<String,O>
 
     /* --------------------------------------------------------------- */
     /**
+     * @param pathSpec the path spec
+     * @param path the path
+     * @param noDefault true to not handle the default path "/" special, false to allow matcher rules to run  
      * @return true if match.
+     * @throws IllegalArgumentException if matcher experienced a failure 
      */
     public static boolean match(String pathSpec, String path, boolean noDefault)
         throws IllegalArgumentException
@@ -431,6 +449,8 @@ public class PathMap<O> extends HashMap<String,O>
 
     /* --------------------------------------------------------------- */
     /** Return the portion of a path that matches a path spec.
+     * @param pathSpec the path spec
+     * @param path the path
      * @return null if no match at all.
      */
     public static String pathMatch(String pathSpec, String path)
@@ -459,6 +479,8 @@ public class PathMap<O> extends HashMap<String,O>
 
     /* --------------------------------------------------------------- */
     /** Return the portion of a path that is after a path spec.
+     * @param pathSpec the path spec
+     * @param path the path
      * @return The path info string
      */
     public static String pathInfo(String pathSpec, String path)

jetty-http/src/test/java/org/eclipse/jetty/http/HttpParserTest.java

@@ -46,6 +46,7 @@ public class HttpParserTest
      * Parse until {@link State#END} state.
      * If the parser is already in the END state, then it is {@link HttpParser#reset()} and re-parsed.
      * @param parser The parser to test
+     * @param buffer the buffer to parse
      * @throws IllegalStateException If the buffers have already been partially parsed.
      */
     public static void parseAll(HttpParser parser, ByteBuffer buffer)

jetty-http/src/test/java/org/eclipse/jetty/http/PathMapTest.java

@@ -145,6 +145,7 @@ public class PathMapTest
 
     /**
      * See JIRA issue: JETTY-88.
+     * @throws Exception failed test
      */
     @Test
     public void testPathMappingsOnlyMatchOnDirectoryNames() throws Exception