464727 - Update Javadoc for Java 8 DocLint

+ Fixing javadoc in jetty-io

jetty-io/src/main/java/org/eclipse/jetty/io/ByteArrayEndPoint.java

@@ -73,7 +73,8 @@ public class ByteArrayEndPoint extends AbstractEndPoint
 
     /* ------------------------------------------------------------ */
     /**
-     *
+     * @param input the input bytes 
+     * @param outputSize the output size
      */
     public ByteArrayEndPoint(byte[] input, int outputSize)
     {
@@ -82,7 +83,8 @@ public class ByteArrayEndPoint extends AbstractEndPoint
 
     /* ------------------------------------------------------------ */
     /**
-     *
+     * @param input the input string (converted to bytes using default encoding charset) 
+     * @param outputSize the output size
      */
     public ByteArrayEndPoint(String input, int outputSize)
     {
@@ -235,6 +237,7 @@ public class ByteArrayEndPoint extends AbstractEndPoint
 
     /* ------------------------------------------------------------ */
     /**
+     * @param charset the charset to encode the output as
      * @return Returns the out.
      */
     public String getOutputString(Charset charset)
@@ -265,6 +268,7 @@ public class ByteArrayEndPoint extends AbstractEndPoint
 
     /* ------------------------------------------------------------ */
     /**
+     * @param charset the charset to encode the output as
      * @return Returns the out.
      */
     public String takeOutputString(Charset charset)

jetty-io/src/main/java/org/eclipse/jetty/io/ClientConnectionFactory.java

@@ -52,7 +52,7 @@ public interface ClientConnectionFactory
          * {@link EndPoint} associated with {@code oldConnection}, performing connection lifecycle management.
          * <p>
          * The {@code oldConnection} will be closed by invoking {@link org.eclipse.jetty.io.Connection#onClose()}
-         * and the {@code newConnection} will be opened by invoking {@link org.eclipse.jetty.io.Connection#onOpen(ByteBuffer)}.
+         * and the {@code newConnection} will be opened by invoking {@link org.eclipse.jetty.io.Connection#onOpen()}.
          * @param oldConnection the old connection to replace
          * @param newConnection the new connection replacement
          */

jetty-io/src/main/java/org/eclipse/jetty/io/Connection.java

@@ -24,8 +24,8 @@ import java.nio.ByteBuffer;
 /**
  * <p>A {@link Connection} is associated to an {@link EndPoint} so that I/O events
  * happening on the {@link EndPoint} can be processed by the {@link Connection}.</p>
- * <p>A typical implementation of {@link Connection} overrides {@link #onOpen(ByteBuffer)} to
- * {@link EndPoint#fillInterested(Callback) set read interest} on the {@link EndPoint},
+ * <p>A typical implementation of {@link Connection} overrides {@link #onOpen()} to
+ * {@link EndPoint#fillInterested(org.eclipse.jetty.util.Callback) set read interest} on the {@link EndPoint},
  * and when the {@link EndPoint} signals read readyness, this {@link Connection} can
  * read bytes from the network and interpret them.</p>
  */
@@ -78,7 +78,7 @@ public interface Connection extends Closeable
         /**
          * <p>Callback method invoked when this {@link Connection} is upgraded.</p>
          * <p>This must be called before {@link #onOpen()}.</p>
-         * @param prefilledBuffer An optional buffer that can contain prefilled data. Typically this
+         * @param prefilled An optional buffer that can contain prefilled data. Typically this
          * results from an upgrade of one protocol to the other where the old connection has buffered
          * data destined for the new connection.  The new connection must take ownership of the buffer
          * and is responsible for returning it to the buffer pool

jetty-io/src/main/java/org/eclipse/jetty/io/EndPoint.java

@@ -27,6 +27,7 @@ import java.nio.channels.WritePendingException;
 
 import org.eclipse.jetty.util.Callback;
 import org.eclipse.jetty.util.FutureCallback;
+import org.eclipse.jetty.util.IteratingCallback;
 
 /**
  *
@@ -39,21 +40,21 @@ import org.eclipse.jetty.util.FutureCallback;
  * some inefficiencies.</p>
  * <p>This class will frequently be used in conjunction with some of the utility
  * implementations of {@link Callback}, such as {@link FutureCallback} and
- * {@link ExecutorCallback}. Examples are:</p>
+ * {@link IteratingCallback}. Examples are:</p>
  *
  * <h3>Blocking Read</h3>
  * <p>A FutureCallback can be used to block until an endpoint is ready to be filled
- * from:
+ * from:</p>
  * <blockquote><pre>
  * FutureCallback&lt;String&gt; future = new FutureCallback&lt;&gt;();
  * endpoint.fillInterested("ContextObj",future);
  * ...
  * String context = future.get(); // This blocks
  * int filled=endpoint.fill(mybuffer);
- * </pre></blockquote></p>
+ * </pre></blockquote>
  *
  * <h3>Dispatched Read</h3>
- * <p>By using a different callback, the read can be done asynchronously in its own dispatched thread:
+ * <p>By using a different callback, the read can be done asynchronously in its own dispatched thread:</p>
  * <blockquote><pre>
  * endpoint.fillInterested("ContextObj",new ExecutorCallback&lt;String&gt;(executor)
  * {
@@ -64,22 +65,22 @@ import org.eclipse.jetty.util.FutureCallback;
  *   }
  *   public void onFailed(String context,Throwable cause) {...}
  * });
- * </pre></blockquote></p>
+ * </pre></blockquote>
  * <p>The executor callback can also be customized to not dispatch in some circumstances when
  * it knows it can use the callback thread and does not need to dispatch.</p>
  *
  * <h3>Blocking Write</h3>
  * <p>The write contract is that the callback complete is not called until all data has been
- * written or there is a failure.  For blocking this looks like:
+ * written or there is a failure.  For blocking this looks like:</p>
  * <blockquote><pre>
  * FutureCallback&lt;String&gt; future = new FutureCallback&lt;&gt;();
  * endpoint.write("ContextObj",future,headerBuffer,contentBuffer);
  * String context = future.get(); // This blocks
- * </pre></blockquote></p>
+ * </pre></blockquote>
  *
  * <h3>Dispatched Write</h3>
  * <p>Note also that multiple buffers may be passed in write so that gather writes
- * can be done:
+ * can be done:</p>
  * <blockquote><pre>
  * endpoint.write("ContextObj",new ExecutorCallback&lt;String&gt;(executor)
  * {
@@ -90,7 +91,7 @@ import org.eclipse.jetty.util.FutureCallback;
  *   }
  *   public void onFailed(String context,Throwable cause) {...}
  * },headerBuffer,contentBuffer);
- * </pre></blockquote></p>
+ * </pre></blockquote>
  */
 public interface EndPoint extends Closeable
 {
@@ -159,7 +160,7 @@ public interface EndPoint extends Closeable
      * operation, the position is unchanged and the limit is increased to reflect the new data filled.
      * @return an <code>int</code> value indicating the number of bytes
      * filled or -1 if EOF is read or the input is shutdown.
-     * @throws EofException If the endpoint is closed.
+     * @throws IOException if the endpoint is closed.
      */
     int fill(ByteBuffer buffer) throws IOException;
 
@@ -168,10 +169,10 @@ public interface EndPoint extends Closeable
      * Flush data from the passed header/buffer to this endpoint.  As many bytes as can be consumed
      * are taken from the header/buffer position up until the buffer limit.  The header/buffers position
      * is updated to indicate how many bytes have been consumed.
+     * @param buffer the buffers to flush
      * @return True IFF all the buffers have been consumed and the endpoint has flushed the data to its 
      * destination (ie is not buffering any data).
-     *
-     * @throws EofException If the endpoint is closed or output is shutdown.
+     * @throws IOException If the endpoint is closed or output is shutdown.
      */
     boolean flush(ByteBuffer... buffer) throws IOException;
 
@@ -185,13 +186,13 @@ public interface EndPoint extends Closeable
     /** Get the max idle time in ms.
      * <p>The max idle time is the time the endpoint can be idle before
      * extraordinary handling takes place.
-     * @return the max idle time in ms or if ms <= 0 implies an infinite timeout
+     * @return the max idle time in ms or if ms &lt;= 0 implies an infinite timeout
      */
     long getIdleTimeout();
 
     /* ------------------------------------------------------------ */
     /** Set the idle timeout.
-     * @param idleTimeout the idle timeout in MS. Timeout <= 0 implies an infinite timeout
+     * @param idleTimeout the idle timeout in MS. Timeout &lt;= 0 implies an infinite timeout
      */
     void setIdleTimeout(long idleTimeout);
 

jetty-io/src/main/java/org/eclipse/jetty/io/FillInterest.java

@@ -43,11 +43,11 @@ public abstract class FillInterest
 
     /**
      * Call to register interest in a callback when a read is possible.
-     * The callback will be called either immediately if {@link #needsFill()}
+     * The callback will be called either immediately if {@link #needsFillInterest()}
      * returns true or eventually once {@link #fillable()} is called.
      *
      * @param callback the callback to register
-     * @throws ReadPendingException
+     * @throws ReadPendingException if unable to read due to pending read op
      */
     public void register(Callback callback) throws ReadPendingException
     {
@@ -105,7 +105,8 @@ public abstract class FillInterest
     
     /**
      * Call to signal a failure to a registered interest
-     *
+     * 
+     * @param cause the cause of the failure 
      * @return true if the cause was passed to a {@link Callback} instance
      */
     public boolean onFail(Throwable cause)
@@ -137,7 +138,7 @@ public abstract class FillInterest
      * Abstract method to be implemented by the Specific ReadInterest to
      * schedule a future call to {@link #fillable()} or {@link #onFail(Throwable)}
      *
-     * @throws IOException
+     * @throws IOException if unable to fulfill interest in fill
      */
     abstract protected void needsFillInterest() throws IOException;
 }

jetty-io/src/main/java/org/eclipse/jetty/io/SelectorManager.java

@@ -97,6 +97,7 @@ public abstract class SelectorManager extends AbstractLifeCycle implements Dumpa
     }
 
     /**
+     * @return the selector priority delta
      * @deprecated not implemented
      */
     @Deprecated
@@ -106,6 +107,7 @@ public abstract class SelectorManager extends AbstractLifeCycle implements Dumpa
     }
 
     /**
+     * @param selectorPriorityDelta the selector priority delta
      * @deprecated not implemented
      */
     @Deprecated
@@ -189,6 +191,7 @@ public abstract class SelectorManager extends AbstractLifeCycle implements Dumpa
     }
 
     /**
+     * @param channel the channel to accept
      * @see #accept(SocketChannel, Object)
      */
     public void accept(SocketChannel channel)
@@ -233,7 +236,7 @@ public abstract class SelectorManager extends AbstractLifeCycle implements Dumpa
      * be overridden by subclasses if a server channel is provided.
      *
      * @param channel the
-     * @throws IOException
+     * @throws IOException if unable to accept channel
      */
     protected void accepted(SocketChannel channel) throws IOException
     {
@@ -368,7 +371,7 @@ public abstract class SelectorManager extends AbstractLifeCycle implements Dumpa
      * @param endpoint   the endpoint
      * @param attachment the attachment
      * @return a new connection
-     * @throws IOException
+     * @throws IOException if unable to create new connection
      * @see #newEndPoint(SocketChannel, ManagedSelector, SelectionKey)
      */
     public abstract Connection newConnection(SocketChannel channel, EndPoint endpoint, Object attachment) throws IOException;

jetty-io/src/main/java/org/eclipse/jetty/io/WriteFlusher.java

@@ -38,9 +38,8 @@ import org.eclipse.jetty.util.log.Logger;
  * A Utility class to help implement {@link EndPoint#write(Callback, ByteBuffer...)} by calling
  * {@link EndPoint#flush(ByteBuffer...)} until all content is written.
  * The abstract method {@link #onIncompleteFlush()} is called when not all content has been written after a call to
- * flush and should organise for the {@link #completeWrite()} method to be called when a subsequent call to flush
+ * flush and should organize for the {@link #completeWrite()} method to be called when a subsequent call to flush
  * should  be able to make more progress.
- * <p>
  */
 abstract public class WriteFlusher
 {
@@ -288,6 +287,7 @@ abstract public class WriteFlusher
      *
      * @param callback the callback to call on either failed or complete
      * @param buffers the buffers to flush to the endpoint
+     * @throws WritePendingException if unable to write due to prior pending write
      */
     public void write(Callback callback, ByteBuffer... buffers) throws WritePendingException
     {
@@ -397,7 +397,7 @@ abstract public class WriteFlusher
     /** Flush the buffers iteratively until no progress is made
      * @param buffers The buffers to flush
      * @return The unflushed buffers, or null if all flushed
-     * @throws IOException
+     * @throws IOException if unable to flush
      */
     protected ByteBuffer[] flush(ByteBuffer[] buffers) throws IOException
     {

jetty-io/src/test/java/org/eclipse/jetty/io/MappedByteBufferPoolTest.java

@@ -90,6 +90,7 @@ public class MappedByteBufferPoolTest
     /**
      * In a scenario where MappedByteBufferPool is being used improperly, such as releasing a buffer that wasn't created/acquired by the MappedByteBufferPool,
      * an assertion is tested for.
+     * @throws Exception test failure
      */
     @Test
     public void testReleaseAssertion() throws Exception