464727 - Update Javadoc for Java 8 DocLint

jetty-client/src/main/java/org/eclipse/jetty/client/HttpClient.java

@@ -309,6 +309,9 @@ public class HttpClient extends ContainerLifeCycle
      *
      * @param uri the URI to GET
      * @return the {@link ContentResponse} for the request
+     * @throws InterruptedException if send threading has been interrupted
+     * @throws ExecutionException the execution failed
+     * @throws TimeoutException the send timed out
      * @see #GET(URI)
      */
     public ContentResponse GET(String uri) throws InterruptedException, ExecutionException, TimeoutException
@@ -321,6 +324,9 @@ public class HttpClient extends ContainerLifeCycle
      *
      * @param uri the URI to GET
      * @return the {@link ContentResponse} for the request
+     * @throws InterruptedException if send threading has been interrupted
+     * @throws ExecutionException the execution failed
+     * @throws TimeoutException the send timed out
      * @see #newRequest(URI)
      */
     public ContentResponse GET(URI uri) throws InterruptedException, ExecutionException, TimeoutException
@@ -334,6 +340,9 @@ public class HttpClient extends ContainerLifeCycle
      * @param uri the URI to POST
      * @param fields the fields composing the form name/value pairs
      * @return the {@link ContentResponse} for the request
+     * @throws InterruptedException if send threading has been interrupted
+     * @throws ExecutionException the execution failed
+     * @throws TimeoutException the send timed out
      */
     public ContentResponse FORM(String uri, Fields fields) throws InterruptedException, ExecutionException, TimeoutException
     {
@@ -346,6 +355,9 @@ public class HttpClient extends ContainerLifeCycle
      * @param uri the URI to POST
      * @param fields the fields composing the form name/value pairs
      * @return the {@link ContentResponse} for the request
+     * @throws InterruptedException if send threading has been interrupted
+     * @throws ExecutionException the execution failed
+     * @throws TimeoutException the send timed out
      */
     public ContentResponse FORM(URI uri, Fields fields) throws InterruptedException, ExecutionException, TimeoutException
     {

jetty-client/src/main/java/org/eclipse/jetty/client/HttpContent.java

@@ -42,7 +42,7 @@ import org.eclipse.jetty.util.log.Logger;
  *      |   |  |   |  |   |  |   |  |   |
  *      +---+  +---+  +---+  +---+  +---+
  *   ^           ^                    ^    ^
- *   |           | --> advance()      |    |
+ *   |           | --> advance()      |    |
  *   |           |                  last   |
  *   |           |                         |
  * before        |                        after

jetty-client/src/main/java/org/eclipse/jetty/client/HttpConversation.java

@@ -41,42 +41,42 @@ public class HttpConversation extends AttributesMap
      * This list changes as the conversation proceeds, as follows:
      * <ol>
      * <li>
-     *     request R1 send => conversation.updateResponseListeners(null)
+     *     request R1 send =&gt; conversation.updateResponseListeners(null)
      *     <ul>
      *         <li>exchanges in conversation: E1</li>
      *         <li>listeners to be notified: E1.listeners</li>
      *     </ul>
      * </li>
      * <li>
-     *     response R1 arrived, 401 => conversation.updateResponseListeners(AuthenticationProtocolHandler.listener)
+     *     response R1 arrived, 401 =&gt; conversation.updateResponseListeners(AuthenticationProtocolHandler.listener)
      *     <ul>
      *         <li>exchanges in conversation: E1</li>
      *         <li>listeners to be notified: AuthenticationProtocolHandler.listener</li>
      *     </ul>
      * </li>
      * <li>
-     *     request R2 send => conversation.updateResponseListeners(null)
+     *     request R2 send =&gt; conversation.updateResponseListeners(null)
      *     <ul>
      *         <li>exchanges in conversation: E1 + E2</li>
      *         <li>listeners to be notified: E2.listeners + E1.listeners</li>
      *     </ul>
      * </li>
      * <li>
-     *     response R2 arrived, 302 => conversation.updateResponseListeners(RedirectProtocolHandler.listener)
+     *     response R2 arrived, 302 =&gt; conversation.updateResponseListeners(RedirectProtocolHandler.listener)
      *     <ul>
      *         <li>exchanges in conversation: E1 + E2</li>
      *         <li>listeners to be notified: E2.listeners + RedirectProtocolHandler.listener</li>
      *     </ul>
      * </li>
      * <li>
-     *     request R3 send => conversation.updateResponseListeners(null)
+     *     request R3 send =&gt; conversation.updateResponseListeners(null)
      *     <ul>
      *         <li>exchanges in conversation: E1 + E2 + E3</li>
      *         <li>listeners to be notified: E3.listeners + E1.listeners</li>
      *     </ul>
      * </li>
      * <li>
-     *     response R3 arrived, 200 => conversation.updateResponseListeners(null)
+     *     response R3 arrived, 200 =&gt; conversation.updateResponseListeners(null)
      *     <ul>
      *         <li>exchanges in conversation: E1 + E2 + E3</li>
      *         <li>listeners to be notified: E3.listeners + E1.listeners</li>

jetty-client/src/main/java/org/eclipse/jetty/client/HttpReceiver.java

@@ -286,6 +286,7 @@ public abstract class HttpReceiver
      *
      * @param exchange the HTTP exchange
      * @param buffer the response HTTP content buffer
+     * @param callback the callback
      * @return whether the processing should continue
      */
     protected boolean responseContent(HttpExchange exchange, ByteBuffer buffer, final Callback callback)

jetty-client/src/main/java/org/eclipse/jetty/client/HttpSender.java

@@ -41,9 +41,9 @@ import org.eclipse.jetty.util.log.Logger;
  * {@link HttpSender} governs two state machines.
  * <p>
  * The request state machine is updated by {@link HttpSender} as the various steps of sending a request
- * are executed, see {@link RequestState}.
+ * are executed, see <code>RequestState</code>.
  * At any point in time, a user thread may abort the request, which may (if the request has not been
- * completely sent yet) move the request state machine to {@link RequestState#FAILURE}.
+ * completely sent yet) move the request state machine to <code>RequestState#FAILURE</code>.
  * The request state machine guarantees that the request steps are executed (by I/O threads) only if
  * the request has not been failed already.
  * <p>

jetty-client/src/main/java/org/eclipse/jetty/client/api/Authentication.java

@@ -49,7 +49,7 @@ public interface Authentication
 
     /**
      * Executes the authentication mechanism for the given request, returning a {@link Result} that can be
-     * used to actually authenticate the request via {@link Result#apply(Request)}.
+     * used to actually authenticate the request via {@link org.eclipse.jetty.client.api.Authentication.Result#apply(Request)}.
      * <p>
      * If a request for {@code "/secure"} returns a {@link Result}, then the result may be used for other
      * requests such as {@code "/secure/foo"} or {@code "/secure/bar"}, unless those resources are protected
@@ -117,7 +117,7 @@ public interface Authentication
     }
 
     /**
-     * {@link Result} holds the information needed to authenticate a {@link Request} via {@link #apply(Request)}.
+     * {@link Result} holds the information needed to authenticate a {@link Request} via {@link org.eclipse.jetty.client.api.Authentication.Result#apply(org.eclipse.jetty.client.api.Request)}.
      */
     public static interface Result
     {

jetty-client/src/main/java/org/eclipse/jetty/client/api/ContentProvider.java

@@ -30,7 +30,7 @@ import org.eclipse.jetty.client.util.PathContentProvider;
  * <p>
  * Implementations should return an {@link Iterator} over the request content.
  * If the request content comes from a source that needs to be closed (for
- * example, an {@link InputStream}), then the iterator implementation class
+ * example, an {@link java.io.InputStream}), then the iterator implementation class
  * must implement {@link Closeable} and will be closed when the request is
  * completed (either successfully or failed).
  * <p>

jetty-client/src/main/java/org/eclipse/jetty/client/api/Request.java

@@ -205,6 +205,7 @@ public interface Request
 
     /**
      * @param content the content provider of this request
+     * @param contentType the content type
      * @return this request object
      */
     Request content(ContentProvider content, String contentType);
@@ -285,6 +286,7 @@ public interface Request
     /**
      * @param listenerClass the class of the listener, or null for all listeners classes
      * @return the listeners for request events of the given class
+     * @param <T> the type of listener class
      */
     <T extends RequestListener> List<T> getRequestListeners(Class<T> listenerClass);
 
@@ -397,6 +399,9 @@ public interface Request
      * The method returns when the {@link Response.CompleteListener complete event} is fired.
      *
      * @return a {@link ContentResponse} for this request
+     * @throws InterruptedException if send thread is interrupted
+     * @throws TimeoutException if send times out
+     * @throws ExecutionException if execution fails
      * @see Response.CompleteListener#onComplete(Result)
      */
     ContentResponse send() throws InterruptedException, TimeoutException, ExecutionException;
@@ -498,6 +503,7 @@ public interface Request
          * Callback method invoked when a chunk of request content has been sent successfully.
          * Changes to bytes in the given buffer have no effect, as the content has already been sent.
          * @param request the request that has been committed
+         * @param content the content
          */
         public void onContent(Request request, ByteBuffer content);
     }

jetty-client/src/main/java/org/eclipse/jetty/client/api/Response.java

@@ -46,7 +46,9 @@ public interface Response
     Request getRequest();
 
     /**
-     * @return the response listener passed to {@link Request#send(CompleteListener)}
+     * @param listenerClass the listener class
+     * @return the response listener passed to {@link org.eclipse.jetty.client.api.Request#send(org.eclipse.jetty.client.api.Response.CompleteListener)}
+     * @param <T> the type of class
      */
     <T extends ResponseListener> List<T> getListeners(Class<T> listenerClass);
 

jetty-client/src/main/java/org/eclipse/jetty/client/package-info.java

@@ -21,31 +21,33 @@
  * 
  * This package provides APIs, utility classes and an implementation of an asynchronous HTTP client.
  * <p>
- * The core class is {@link org.eclipse.jetty.client.api.HttpClient}, which acts as a central configuration object (for example
+ * The core class is {@link org.eclipse.jetty.client.HttpClient}, which acts as a central configuration object (for example
- * for {@link org.eclipse.jetty.client.api.HttpClient#setIdleTimeout(long) idle timeouts}, {@link org.eclipse.jetty.client.api.HttpClient#setMaxConnectionsPerDestination(int)
+ * for {@link org.eclipse.jetty.client.HttpClient#setIdleTimeout(long) idle timeouts}, {@link org.eclipse.jetty.client.HttpClient#setMaxConnectionsPerDestination(int)
- * max connections per destination}, etc.) and as a factory for {@link Request} objects.
+ * max connections per destination}, etc.) and as a factory for {@link org.eclipse.jetty.client.api.Request} objects.
  * <p>
  * The HTTP protocol is based on the request/response paradigm, a unit that in this implementation is called
- * <em>exchange</em> and is represented by {@link org.eclipse.jetty.client.api.HttpExchange}.
+ * <em>exchange</em> and is represented by {@link org.eclipse.jetty.client.HttpExchange}.
  * An initial request may trigger a sequence of exchanges with one or more servers, called a <em>conversation</em>
- * and represented by {@link org.eclipse.jetty.client.api.HttpConversation}. A typical example of a conversation is a redirect, where
+ * and represented by {@link org.eclipse.jetty.client.HttpConversation}. A typical example of a conversation is a redirect, where
  * upon a request for a resource URI, the server replies with a redirect (for example with the 303 status code)
  * to another URI. This conversation is made of a first exchange made of the original request and its 303 response,
  * and of a second exchange made of the request for the new URI and its 200 response.
  * <p>
- * {@link org.eclipse.jetty.client.api.HttpClient} holds a number of {@link org.eclipse.jetty.client.api.HttpDestination destinations}, which in turn hold a number of
+ * {@link org.eclipse.jetty.client.HttpClient} holds a number of {@link org.eclipse.jetty.client.api.Destination destinations}, which in turn hold a number of
- * pooled {@link org.eclipse.jetty.client.api.HttpConnection connections}.
+ * pooled {@link org.eclipse.jetty.client.api.Connection connections}.
  * <p>
  * When a request is sent, its exchange is associated to a connection, either taken from an idle queue or created
  * anew, and when both the request and response are completed, the exchange is disassociated from the connection.
  * Conversations may span multiple connections on different destinations, and therefore are maintained at the
- * {@link org.eclipse.jetty.client.api.HttpClient} level.
+ * {@link org.eclipse.jetty.client.HttpClient} level.
  * <p>
  * Applications may decide to send the request and wait for the response in a blocking way, using
  * {@link org.eclipse.jetty.client.api.Request#send()}.
  * Alternatively, application may ask to be notified of response events asynchronously, using
- * {@link org.eclipse.jetty.client.api.Request#send(Response.Listener)}.
+ * {@link org.eclipse.jetty.client.api.Request#send(org.eclipse.jetty.client.api.Response.CompleteListener)}.
  */
 package org.eclipse.jetty.client;
 
+import org.eclipse.jetty.client.api.Response;
+
 

jetty-client/src/main/java/org/eclipse/jetty/client/util/DeferredContentProvider.java

@@ -73,7 +73,7 @@ import org.eclipse.jetty.util.Callback;
  *             .content(content)
  *             .send(new Response.CompleteListener()
  *             {
- *                 &#64Override
+ *                 @Override
  *                 public void onComplete(Result result)
  *                 {
  *                     // Your logic here

jetty-client/src/main/java/org/eclipse/jetty/client/util/OutputStreamContentProvider.java

@@ -61,7 +61,7 @@ import org.eclipse.jetty.util.Callback;
  *             .content(content)
  *             .send(new Response.CompleteListener()
  *             {
- *                 &#64Override
+ *                 @Override
  *                 public void onComplete(Result result)
  *                 {
  *                     // Your logic here

jetty-client/src/test/java/org/eclipse/jetty/client/HostnameVerificationTest.java

@@ -95,7 +95,7 @@ public class HostnameVerificationTest
      * http://www.ietf.org/rfc/rfc2818.txt section 3.1. It uses a certificate with a common name different to localhost
      * and sends a request to localhost. This should fail with a SSLHandshakeException.
      *
-     * @throws Exception
+     * @throws Exception on test failure
      */
     @Test
     public void simpleGetWithHostnameVerificationEnabledTest() throws Exception
@@ -133,7 +133,8 @@ public class HostnameVerificationTest
      * This test has hostname verification disabled and connecting, ssl handshake and sending the request should just
      * work fine.
      *
-     * @throws Exception
+     * @throws Exception on test failure
+     * 
      */
     @Test
     public void simpleGetWithHostnameVerificationDisabledTest() throws Exception
@@ -154,7 +155,7 @@ public class HostnameVerificationTest
      * This test has hostname verification disabled by setting trustAll to true and connecting,
      * ssl handshake and sending the request should just work fine.
      *
-     * @throws Exception
+     * @throws Exception on test failure
      */
     @Test
     public void trustAllDisablesHostnameVerificationTest() throws Exception

jetty-continuation/src/main/java/org/eclipse/jetty/continuation/Continuation.java

@@ -24,10 +24,9 @@ import javax.servlet.ServletRequest;
 import javax.servlet.ServletResponse;
 import javax.servlet.ServletResponseWrapper;
 
-/* ------------------------------------------------------------ */
 /**
  * Continuation.
- * 
+ * <p> 
  * A continuation is a mechanism by which a HTTP Request can be suspended and
  * restarted after a timeout or an asynchronous event has occurred.
  * <p>
@@ -52,7 +51,7 @@ import javax.servlet.ServletResponseWrapper;
  * <p>
  * There are two distinct style of operation of the continuation API.
  * </p>
- * <h3>Suspend/Resume Usage</h3> 
+ * <h1>Suspend/Resume Usage</h1> 
  * <p>The suspend/resume style is used when a servlet and/or
  * filter is used to generate the response after a asynchronous wait that is
  * terminated by an asynchronous handler.
@@ -87,7 +86,7 @@ import javax.servlet.ServletResponseWrapper;
  *     response.getOutputStream().write(process(results));
  *   }
  * </pre> 
- * <h3>Suspend/Complete Usage</h3> 
+ * <h1>Suspend/Complete Usage</h1> 
  * <p>
  * The suspend/complete style is used when an asynchronous handler is used to 
  * generate the response:
@@ -152,7 +151,7 @@ public interface Continuation
      * @param timeoutMs
      *            The time in milliseconds to wait before expiring this
      *            continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}.
-     *            A timeout of <=0 means the continuation will never expire.
+     *            A timeout of &lt;=0 means the continuation will never expire.
      */
     void setTimeout(long timeoutMs);
 
@@ -164,8 +163,8 @@ public interface Continuation
      * <p>
      * After this method has been called, the lifecycle of the request will be
      * extended beyond the return to the container from the
-     * {@link Servlet#service(ServletRequest, ServletResponse)} method and
+     * {@link javax.servlet.Servlet#service(ServletRequest, ServletResponse)} method and
-     * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
+     * {@link javax.servlet.Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
      * calls. When a suspended request is returned to the container after
      * a dispatch, then the container will not commit the associated response
      * (unless an exception other than {@link ContinuationThrowable} is thrown).
@@ -200,8 +199,8 @@ public interface Continuation
      * <p>
      * After this method has been called, the lifecycle of the request will be
      * extended beyond the return to the container from the
-     * {@link Servlet#service(ServletRequest, ServletResponse)} method and
+     * {@link javax.servlet.Servlet#service(ServletRequest, ServletResponse)} method and
-     * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
+     * {@link javax.servlet.Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
      * calls. When a suspended request is returned to the container after
      * a dispatch, then the container will not commit the associated response
      * (unless an exception other than {@link ContinuationThrowable} is thrown).
@@ -365,7 +364,7 @@ public interface Continuation
     /** 
      * Add a ContinuationListener.
      * 
-     * @param listener
+     * @param listener the listener
      */
     void addContinuationListener(ContinuationListener listener);
     

jetty-continuation/src/main/java/org/eclipse/jetty/continuation/ContinuationListener.java

@@ -22,13 +22,11 @@ import java.util.EventListener;
 
 import javax.servlet.ServletRequestListener;
 
-
+/** 
-/* ------------------------------------------------------------ */
+ * A Continuation Listener
-/** A Continuation Listener
  * <p>
  * A ContinuationListener may be registered with a call to
  * {@link Continuation#addContinuationListener(ContinuationListener)}.
- *
  */
 public interface ContinuationListener extends EventListener
 {
@@ -38,7 +36,7 @@ public interface ContinuationListener extends EventListener
      * any calls to {@link ServletRequestListener#requestDestroyed(javax.servlet.ServletRequestEvent)}
      * The response may still be written to during the call.
      *
-     * @param continuation
+     * @param continuation the continuation
      */
     public void onComplete(Continuation continuation);
 
@@ -48,7 +46,7 @@ public interface ContinuationListener extends EventListener
      * The response may be written to and the methods
      * {@link Continuation#resume()} or {@link Continuation#complete()}
      * may be called by a onTimeout implementation,
-     * @param continuation
+     * @param continuation the continuation
      */
     public void onTimeout(Continuation continuation);
 

jetty-jmx/src/main/java/org/eclipse/jetty/jmx/ConnectorServer.java

@@ -57,7 +57,7 @@ public class ConnectorServer extends AbstractLifeCycle
      * The actual address of the new connector server, as returned
      * by its getAddress method, will not necessarily be exactly the same.
      * @param name object name string to be assigned to connector server bean
-     * @throws Exception
+     * @throws Exception if unable to setup connector server
      */
     public ConnectorServer(JMXServiceURL serviceURL, String name)
         throws Exception
@@ -77,7 +77,7 @@ public class ConnectorServer extends AbstractLifeCycle
      * be Strings. The appropriate type of each associated value depends on
      * the attribute. The contents of environment are not changed by this call.
      * @param name object name string to be assigned to connector server bean
-     * @throws Exception
+     * @throws Exception if unable to create connector server
      */
     public ConnectorServer(JMXServiceURL svcUrl, Map<String,?> environment, String name)
          throws Exception

jetty-jmx/src/main/java/org/eclipse/jetty/jmx/ObjectMBean.java

@@ -59,18 +59,18 @@ import org.eclipse.jetty.util.annotation.Name;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-/* ------------------------------------------------------------ */
+/** 
-/** ObjectMBean.
+ * ObjectMBean.
+ * <p>
  * A dynamic MBean that can wrap an arbitary Object instance.
  * the attributes and methods exposed by this bean are controlled by
  * the merge of property bundles discovered by names related to all
  * superclasses and all superinterfaces.
- *
+ * <p>
  * Attributes and methods exported may be "Object" and must exist on the
  * wrapped object, or "MBean" and must exist on a subclass of OBjectMBean
  * or "MObject" which exists on the wrapped object, but whose values are
  * converted to MBean object names.
- *
  */
 public class ObjectMBean implements DynamicMBean
 {
@@ -592,7 +592,7 @@ public class ObjectMBean implements DynamicMBean
      * getter and setter methods. Descriptions are obtained with a call to findDescription with the
      * attribute name.
      *
-     * @param method
+     * @param method the method to define
      * @param attributeAnnotation "description" or "access:description" or "type:access:description"  where type is
      * one of: <ul>
      * <li>"Object" The field/method is on the managed object.
@@ -601,6 +601,7 @@ public class ObjectMBean implements DynamicMBean
      * <li>"MMBean" The field/method is on the mbean proxy object and value should be converted to MBean reference
      * </ul>
      * the access is either "RW" or "RO".
+     * @return the mbean attribute info for the method
      */
     public MBeanAttributeInfo defineAttribute(Method method, ManagedAttribute attributeAnnotation)
     {

jetty-servlets/src/main/java/org/eclipse/jetty/servlets/CGI.java

@@ -44,11 +44,9 @@ import org.eclipse.jetty.util.UrlEncoded;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-//-----------------------------------------------------------------------------
 /**
  * CGI Servlet.
  * <p>
- * 
  * The following init parameters are used to configure this servlet:
  * <dl>
  * <dt>cgibinResourceBase</dt>
@@ -69,7 +67,6 @@ import org.eclipse.jetty.util.log.Logger;
  * <dt>ignoreExitState</dt>
  * <dd>If true then do not act on a non-zero exec exit status")</dd>
  * </dl>
- * 
  */
 public class CGI extends HttpServlet
 {
@@ -546,13 +543,18 @@ public class CGI extends HttpServlet
 
         /**
          * Set a name/value pair, null values will be treated as an empty String
+         * @param name the name
+         * @param value the value
          */
         public void set(String name, String value)
         {
             envMap.put(name,name + "=" + StringUtil.nonNull(value));
         }
 
-        /** Get representation suitable for passing to exec. */
+        /** 
+         * Get representation suitable for passing to exec. 
+         * @return the env map as an array 
+         */
         public String[] getEnvArray()
         {
             return envMap.values().toArray(new String[envMap.size()]);

jetty-servlets/src/main/java/org/eclipse/jetty/servlets/ConcatServlet.java

@@ -27,8 +27,9 @@ import javax.servlet.http.HttpServlet;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
-/* ------------------------------------------------------------ */
+/** 
-/** Concatenation Servlet
+ * Concatenation Servlet
+ * <p>
  * This servlet may be used to concatenate multiple resources into
  * a single response.  It is intended to be used to load multiple
  * javascript or css files, but may be used for any content of the
@@ -42,11 +43,11 @@ import javax.servlet.http.HttpServletResponse;
  * relative to the context root.  So these script tags:
  * <pre>
  *  &lt;script type="text/javascript" src="../js/behaviour.js"&gt;&lt;/script&gt;
- *  &lt;script type="text/javascript" src="../js/ajax.js&/chat/chat.js"&gt;&lt;/script&gt;
+ *  &lt;script type="text/javascript" src="../js/ajax.js&amp;/chat/chat.js"&gt;&lt;/script&gt;
  *  &lt;script type="text/javascript" src="../chat/chat.js"&gt;&lt;/script&gt;
  * </pre> can be replaced with the single tag (with the ConcatServlet mapped to /concat):
  * <pre>
- *  &lt;script type="text/javascript" src="../concat?/js/behaviour.js&/js/ajax.js&/chat/chat.js"&gt;&lt;/script&gt;
+ *  &lt;script type="text/javascript" src="../concat?/js/behaviour.js&amp;/js/ajax.js&amp;/chat/chat.js"&gt;&lt;/script&gt;
  * </pre>
  * The {@link ServletContext#getMimeType(String)} method is used to determine the
  * mime type of each resource.  If the types of all resources do not match, then a 415

jetty-servlets/src/main/java/org/eclipse/jetty/servlets/CrossOriginFilter.java

@@ -40,44 +40,62 @@ import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
 /**
- * <p>Implementation of the
+ * Implementation of the
- * <a href="http://www.w3.org/TR/cors/">cross-origin resource sharing</a>.</p>
+ * <a href="http://www.w3.org/TR/cors/">cross-origin resource sharing</a>.
- * <p>A typical example is to use this filter to allow cross-domain
+ * <p>
+ * A typical example is to use this filter to allow cross-domain
  * <a href="http://cometd.org">cometd</a> communication using the standard
  * long polling transport instead of the JSONP transport (that is less
- * efficient and less reactive to failures).</p>
+ * efficient and less reactive to failures).
- * <p>This filter allows the following configuration parameters:
+ * <p>
- * <ul>
+ * This filter allows the following configuration parameters:
- * <li><b>allowedOrigins</b>, a comma separated list of origins that are
+ * <dl>
+ * <dt>allowedOrigins</dt>
+ * <dd>a comma separated list of origins that are
  * allowed to access the resources. Default value is <b>*</b>, meaning all
- * origins.<br>
+ * origins.
+ * <p>
  * If an allowed origin contains one or more * characters (for example
  * http://*.domain.com), then "*" characters are converted to ".*", "."
  * characters are escaped to "\." and the resulting allowed origin
- * interpreted as a regular expression.<br>
+ * interpreted as a regular expression.
+ * <p>
  * Allowed origins can therefore be more complex expressions such as
  * https?://*.domain.[a-z]{3} that matches http or https, multiple subdomains
- * and any 3 letter top-level domain (.com, .net, .org, etc.).</li>
+ * and any 3 letter top-level domain (.com, .net, .org, etc.).</dd>
- * <li><b>allowedMethods</b>, a comma separated list of HTTP methods that
+ * 
+ * <dt>allowedMethods</dt>
+ * <dd>a comma separated list of HTTP methods that
  * are allowed to be used when accessing the resources. Default value is
- * <b>GET,POST,HEAD</b></li>
+ * <b>GET,POST,HEAD</b></dd>
- * <li><b>allowedHeaders</b>, a comma separated list of HTTP headers that
+ * 
+ * <dt>allowedHeaders</dt>
+ * <dd>a comma separated list of HTTP headers that
  * are allowed to be specified when accessing the resources. Default value
  * is <b>X-Requested-With,Content-Type,Accept,Origin</b>. If the value is a single "*",
- * this means that any headers will be accepted.</li>
+ * this means that any headers will be accepted.</dd>
- * <li><b>preflightMaxAge</b>, the number of seconds that preflight requests
+ * 
+ * <dt>preflightMaxAge</dt>
+ * <dd>the number of seconds that preflight requests
  * can be cached by the client. Default value is <b>1800</b> seconds, or 30
- * minutes</li>
+ * minutes</dd>
- * <li><b>allowCredentials</b>, a boolean indicating if the resource allows
+ * 
- * requests with credentials. Default value is <b>true</b></li>
+ * <dt>allowCredentials</dt>
- * <li><b>exposedHeaders</b>, a comma separated list of HTTP headers that
+ * <dd>a boolean indicating if the resource allows
+ * requests with credentials. Default value is <b>true</b></dd>
+ * 
+ * <dt>exposedHeaders</dt>
+ * <dd>a comma separated list of HTTP headers that
  * are allowed to be exposed on the client. Default value is the
- * <b>empty list</b></li>
+ * <b>empty list</b></dd>
- * <li><b>chainPreflight</b>, if true preflight requests are chained to their
+ * 
+ * <dt>chainPreflight</dt>
+ * <dd>if true preflight requests are chained to their
  * target resource for normal handling (as an OPTION request).  Otherwise the
- * filter will response to the preflight. Default is <b>true</b>.</li>
+ * filter will response to the preflight. Default is <b>true</b>.</dd>
- * </ul></p>
+ * 
- * <p>A typical configuration could be:</p>
+ * </dl>
+ * A typical configuration could be:
  * <pre>
  * &lt;web-app ...&gt;
  *     ...

jetty-servlets/src/main/java/org/eclipse/jetty/servlets/DoSFilter.java

@@ -64,7 +64,6 @@ import org.eclipse.jetty.util.thread.Scheduler;
 /**
  * Denial of Service filter
  * <p>
- * <p>
  * This filter is useful for limiting
  * exposure to abuse from request flooding, whether malicious, or as a result of
  * a misconfigured client.
@@ -81,13 +80,12 @@ import org.eclipse.jetty.util.thread.Scheduler;
  * The {@link #extractUserId(ServletRequest request)} function should be
  * implemented, in order to uniquely identify authenticated users.
  * <p>
- * The following init parameters control the behavior of the filter:<dl>
+ * The following init parameters control the behavior of the filter:
- * <p>
+ * <dl>
  * <dt>maxRequestsPerSec</dt>
  * <dd>the maximum number of requests from a connection per
  * second. Requests in excess of this are first delayed,
  * then throttled.</dd>
- * <p>
  * <dt>delayMs</dt>
  * <dd>is the delay given to all requests over the rate limit,
  * before they are considered at all. -1 means just reject request,
@@ -120,7 +118,6 @@ import org.eclipse.jetty.util.thread.Scheduler;
  * <dd>The status code to send if there are too many requests.  By default is 429 (too many requests), but 503 (Unavailable) is 
  * another option</dd>
  * </dl>
- * </p>
  * <p>
  * This filter should be configured for {@link DispatcherType#REQUEST} and {@link DispatcherType#ASYNC} and with 
  * <code>&lt;async-supported&gt;true&lt;/async-supported&gt;</code>.
@@ -787,6 +784,7 @@ public class DoSFilter implements Filter
     /**
      * Get delay (in milliseconds) that is applied to all requests
      * over the rate limit, before they are considered at all.
+     * @return the delay in milliseconds
      */
     @ManagedAttribute("delay applied to all requests over the rate limit (in ms)")
     public long getDelayMs()
@@ -1112,6 +1110,7 @@ public class DoSFilter implements Filter
         }
 
         /**
+         * @param now the time now (in milliseconds)
          * @return the current calculated request rate over the last second
          */
         public boolean isRateExceeded(long now)

jetty-servlets/src/main/java/org/eclipse/jetty/servlets/MultiPartFilter.java

@@ -56,7 +56,6 @@ import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
 
-/* ------------------------------------------------------------ */
 /**
  * Multipart Form Data Filter.
  * <p>
@@ -95,6 +94,7 @@ import org.eclipse.jetty.util.log.Logger;
  * </dl>
  * @deprecated See servlet 3.0 apis like javax.servlet.http.HttpServletRequest.getParts()
  */
+@Deprecated
 public class MultiPartFilter implements Filter
 {
     private static final Logger LOG = Log.getLogger(MultiPartFilter.class);
@@ -243,9 +243,6 @@ public class MultiPartFilter implements Filter
         MultiMap<Object> _params;
 
         /* ------------------------------------------------------------------------------- */
-        /** Constructor.
-         * @param request
-         */
         public Wrapper(HttpServletRequest request, MultiMap map)
         {
             super(request);

jetty-servlets/src/test/java/org/eclipse/jetty/server/handler/gzip/GzipContentLengthTest.java

@@ -133,6 +133,7 @@ public class GzipContentLengthTest
     /**
      * Test with content servlet that does:  
      * AsyncContext create -> timeout -> onTimeout -> write-response -> complete
+     * @throws Exception on test failure
      */
     @Test
     public void testAsyncTimeoutCompleteWrite_Default() throws Exception
@@ -143,6 +144,7 @@ public class GzipContentLengthTest
     /**
      * Test with content servlet that does:  
      * AsyncContext create -> timeout -> onTimeout -> write-response -> complete
+     * @throws Exception on test failure
      */
     @Test
     public void testAsyncTimeoutCompleteWrite_Passed() throws Exception
@@ -153,6 +155,7 @@ public class GzipContentLengthTest
     /**
      * Test with content servlet that does:  
      * AsyncContext create -> timeout -> onTimeout -> dispatch -> write-response
+     * @throws Exception on test failure
      */
     @Test
     public void testAsyncTimeoutDispatchWrite_Default() throws Exception
@@ -163,6 +166,7 @@ public class GzipContentLengthTest
     /**
      * Test with content servlet that does:  
      * AsyncContext create -> timeout -> onTimeout -> dispatch -> write-response
+     * @throws Exception on test failure
      */
     @Test
     public void testAsyncTimeoutDispatchWrite_Passed() throws Exception
@@ -173,6 +177,7 @@ public class GzipContentLengthTest
     /**
      * Test with content servlet that does:  
      * AsyncContext create -> no-timeout -> scheduler.schedule -> dispatch -> write-response
+     * @throws Exception on test failure
      */
     @Test
     public void testAsyncScheduledDispatchWrite_Default() throws Exception
@@ -183,6 +188,7 @@ public class GzipContentLengthTest
     /**
      * Test with content servlet that does:  
      * AsyncContext create -> no-timeout -> scheduler.schedule -> dispatch -> write-response
+     * @throws Exception on test failure
      */
     @Test
     public void testAsyncScheduledDispatchWrite_Passed() throws Exception
@@ -197,7 +203,8 @@ public class GzipContentLengthTest
      * 3) setHeader(content-type)
      * 4) outputStream.write()
      * 
-     * @see <a href="Eclipse Bug 354014">http://bugs.eclipse.org/354014</a>
+     * @throws Exception on test failure
+     * @see <a href="http://bugs.eclipse.org/354014">Eclipse Bug 354014</a>
      */
     @Test
     public void testServletLengthStreamTypeWrite() throws Exception
@@ -212,7 +219,8 @@ public class GzipContentLengthTest
      * 3) getOutputStream()
      * 4) outputStream.write()
      * 
-     * @see <a href="Eclipse Bug 354014">http://bugs.eclipse.org/354014</a>
+     * @throws Exception on test failure
+     * @see <a href="http://bugs.eclipse.org/354014">Eclipse Bug 354014</a>
      */
     @Test
     public void testServletLengthTypeStreamWrite() throws Exception
@@ -227,7 +235,8 @@ public class GzipContentLengthTest
      * 3) setHeader(content-type)
      * 4) outputStream.write()
      * 
-     * @see <a href="Eclipse Bug 354014">http://bugs.eclipse.org/354014</a>
+     * @throws Exception on test failure
+     * @see <a href="http://bugs.eclipse.org/354014">Eclipse Bug 354014</a>
      */
     @Test
     public void testServletStreamLengthTypeWrite() throws Exception
@@ -242,7 +251,8 @@ public class GzipContentLengthTest
      * 3) setHeader(content-type)
      * 4) outputStream.write() (with frequent response flush)
      * 
-     * @see <a href="Eclipse Bug 354014">http://bugs.eclipse.org/354014</a>
+     * @throws Exception on test failure
+     * @see <a href="http://bugs.eclipse.org/354014">Eclipse Bug 354014</a>
      */
     @Test
     public void testServletStreamLengthTypeWriteWithFlush() throws Exception
@@ -257,7 +267,8 @@ public class GzipContentLengthTest
      * 3) setHeader(content-length)
      * 4) outputStream.write()
      * 
-     * @see <a href="Eclipse Bug 354014">http://bugs.eclipse.org/354014</a>
+     * @throws Exception on test failure
+     * @see <a href="http://bugs.eclipse.org/354014">Eclipse Bug 354014</a>
      */
     @Test
     public void testServletStreamTypeLengthWrite() throws Exception
@@ -272,7 +283,8 @@ public class GzipContentLengthTest
      * 3) getOutputStream()
      * 4) outputStream.write()
      * 
-     * @see <a href="Eclipse Bug 354014">http://bugs.eclipse.org/354014</a>
+     * @throws Exception on test failure
+     * @see <a href="http://bugs.eclipse.org/354014">Eclipse Bug 354014</a>
      */
     @Test
     public void testServletTypeLengthStreamWrite() throws Exception
@@ -287,6 +299,7 @@ public class GzipContentLengthTest
      * 3) setHeader(content-length)
      * 4) outputStream.write()
      * 
+     * @throws Exception on test failure
      * @see <a href="Eclipse Bug 354014">http://bugs.eclipse.org/354014</a>
      */
     @Test
@@ -305,7 +318,8 @@ public class GzipContentLengthTest
      * This is done to demonstrate a bug with using HttpOutput.write()
      * while also using GzipFilter
      * 
-     * @see <a href="Eclipse Bug 450873">http://bugs.eclipse.org/450873</a>
+     * @throws Exception on test failure
+     * @see <a href="http://bugs.eclipse.org/450873">Eclipse Bug 450873</a>
      */
     @Test
     public void testHttpOutputWrite() throws Exception

jetty-servlets/src/test/java/org/eclipse/jetty/server/handler/gzip/GzipTester.java

@@ -345,7 +345,8 @@ public class GzipTester
      *            the filename used to on the GET request,.
      * @param testResourceSha1Sum
      *            the sha1sum file that contains the SHA1SUM checksum that will be used to verify that the response contents are what is intended.
-     * @param expectedContentType
+     * @param expectedContentType the expected content type
+     * @throws Exception on test failure
      */
     public void assertIsResponseNotGziped(String requestedFilename, String testResourceSha1Sum, String expectedContentType) throws Exception
     {
@@ -363,9 +364,10 @@ public class GzipTester
      *            the filename used to on the GET request,.
      * @param testResourceSha1Sum
      *            the sha1sum file that contains the SHA1SUM checksum that will be used to verify that the response contents are what is intended.
-     * @param expectedContentType
+     * @param expectedContentType the expected content type
      * @param expectedContentEncoding
      *            can be non-null in some circumstances, eg when dealing with pre-gzipped .svgz files
+     * @throws Exception on test failure
      */
     public void assertIsResponseNotGzipFiltered(String requestedFilename, String testResourceSha1Sum, String expectedContentType, String expectedContentEncoding)
             throws Exception
@@ -531,6 +533,8 @@ public class GzipTester
      *            the filename to create
      * @param filesize
      *            the file size to create (Note: this isn't suitable for creating large multi-megabyte files)
+     * @return the prepared file
+     * @throws IOException if unable to create file
      */
     public File prepareServerFile(String filename, int filesize) throws IOException
     {
@@ -564,6 +568,7 @@ public class GzipTester
      *
      * @param filename
      *            the filename to look for in src/test/resources
+     * @throws IOException if unable to copy file
      */
     public void copyTestServerFile(String filename) throws IOException
     {
@@ -578,6 +583,7 @@ public class GzipTester
      *
      * @param servletClass
      *            the servlet that will provide content.
+     * @throws IOException if unable to set content servlet
      */
     public void setContentServlet(Class<? extends Servlet> servletClass) throws IOException
     {
@@ -612,6 +618,7 @@ public class GzipTester
      *            the path spec for this filter
      * @param dispatches
      *            the set of {@link DispatcherType} to associate with this filter
+     * @throws IOException if unable to add filter
      */
     public void addFilter(FilterHolder holder, String pathSpec, EnumSet<DispatcherType> dispatches) throws IOException
     {

jetty-servlets/src/test/java/org/eclipse/jetty/servlets/MultipartFilterTest.java

@@ -780,10 +780,6 @@ public class MultipartFilterTest
         assertEquals(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, response.getStatus());
     }
 
-    /*
-     * see the testParameterMap test
-     *
-     */
     public static class TestServletParameterMap extends DumpServlet
     {
         @Override
@@ -798,7 +794,7 @@ public class MultipartFilterTest
     /**
      * Validate that the getParameterMap() call is correctly unencoding the parameters in the
      * map that it returns.
-     * @throws Exception
+     * @throws Exception on test failure
      */
     @Test
     public void testParameterMap() throws Exception