Javadoc

Author: garydgregory

src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java

@@ -141,36 +141,38 @@ protected Charset getCharsetDefault() {
     }
 
     /**
-     * Gets an input stream from the origin with open options.
+     * Gets an InputStream from the origin with OpenOption[].
      *
      * @return An input stream
      * @throws IllegalStateException         if the {@code origin} is {@code null}.
      * @throws UnsupportedOperationException if the origin cannot be converted to an {@link InputStream}.
      * @throws IOException                   if an I/O error occurs.
      * @see AbstractOrigin#getInputStream(OpenOption...)
+     * @see #getOpenOptions()
      * @since 2.13.0
      */
     protected InputStream getInputStream() throws IOException {
         return checkOrigin().getInputStream(getOpenOptions());
     }
 
     /**
-     * Gets the OpenOption.
+     * Gets the OpenOption array.
      *
-     * @return the OpenOption.
+     * @return the OpenOption array.
      */
     protected OpenOption[] getOpenOptions() {
         return openOptions;
     }
 
     /**
-     * Gets an OutputStream from the origin with open options.
+     * Gets an OutputStream from the origin with OpenOption[].
      *
      * @return An OutputStream
      * @throws IllegalStateException         if the {@code origin} is {@code null}.
      * @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
      * @throws IOException                   if an I/O error occurs.
      * @see AbstractOrigin#getOutputStream(OpenOption...)
+     * @see #getOpenOptions()
      * @since 2.13.0
      */
     protected OutputStream getOutputStream() throws IOException {
@@ -191,13 +193,14 @@ protected Path getPath() {
     }
 
     /**
-     * Gets an writer from the origin with open options.
+     * Gets a Writer from the origin with OpenOption[].
      *
      * @return An writer.
      * @throws IllegalStateException         if the {@code origin} is {@code null}.
      * @throws UnsupportedOperationException if the origin cannot be converted to a {@link Writer}.
      * @throws IOException                   if an I/O error occurs.
      * @see AbstractOrigin#getOutputStream(OpenOption...)
+     * @see #getOpenOptions()
      * @since 2.13.0
      */
     protected Writer getWriter() throws IOException {

src/main/java/org/apache/commons/io/filefilter/WildcardFileFilter.java

@@ -40,7 +40,7 @@
  * command lines. The check is case-sensitive by default. See {@link FilenameUtils#wildcardMatchOnSystem(String,String)} for more information.
  * </p>
  * <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
  * </p>
  * <p>
  * For example:

src/main/java/org/apache/commons/io/input/AutoCloseInputStream.java

@@ -24,52 +24,57 @@
 import org.apache.commons.io.build.AbstractStreamBuilder;
 
 /**
- * Proxy stream that closes and discards the underlying stream as soon as the
- * end of input has been reached or when the stream is explicitly closed.
- * Not even a reference to the underlying stream is kept after it has been
- * closed, so any allocated in-memory buffers can be freed even if the
- * client application still keeps a reference to the proxy stream.
+ * Proxy stream that closes and discards the underlying stream as soon as the end of input has been reached or when the stream is explicitly closed. Not even a
+ * reference to the underlying stream is kept after it has been closed, so any allocated in-memory buffers can be freed even if the client application still
+ * keeps a reference to the proxy stream.
  * <p>
- * This class is typically used to release any resources related to an open
- * stream as soon as possible even if the client application (by not explicitly
- * closing the stream when no longer needed) or the underlying stream (by not
- * releasing resources once the last byte has been read) do not do that.
+ * This class is typically used to release any resources related to an open stream as soon as possible even if the client application (by not explicitly closing
+ * the stream when no longer needed) or the underlying stream (by not releasing resources once the last byte has been read) do not do that.
+ * </p>
+ * <p>
+ * To build an instance, use {@link Builder}.
  * </p>
  *
  * @since 1.4
+ * @see Builder
  */
 public class AutoCloseInputStream extends ProxyInputStream {
 
+    // @formatter:off
     /**
      * Builds a new {@link AutoCloseInputStream} instance.
+     *
      * <p>
      * For example:
      * </p>
-     *
      * <pre>{@code
      * AutoCloseInputStream s = AutoCloseInputStream.builder()
      *   .setPath(path)
      *   .get();}
      * </pre>
-     *
      * <pre>{@code
      * AutoCloseInputStream s = AutoCloseInputStream.builder()
      *   .setInputStream(inputStream)
      *   .get();}
      * </pre>
      *
+     * @see #get()
      * @since 2.13.0
      */
+    // @formatter:on
     public static class Builder extends AbstractStreamBuilder<AutoCloseInputStream, Builder> {
 
         /**
-         * Constructs a new instance.
+         * Builds a new {@link AutoCloseInputStream}.
          * <p>
-         * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+         * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
          * </p>
          * <p>
-         * This builder use the aspects InputStream, OpenOption[], include, and ByteOrderMark[].
+         * This builder use the following aspects:
          * </p>
+         * <ul>
+         * <li>{@link #getInputStream()}</li>
+         * </ul>
          *
          * @return a new instance.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.
@@ -121,15 +126,14 @@ protected void afterRead(final int n) throws IOException {
     }
 
     /**
-     * Closes the underlying input stream and replaces the reference to it
-     * with a {@link ClosedInputStream} instance.
+     * Closes the underlying input stream and replaces the reference to it with a {@link ClosedInputStream} instance.
      * <p>
-     * This method is automatically called by the read methods when the end
-     * of input has been reached.
+     * This method is automatically called by the read methods when the end of input has been reached.
+     * </p>
      * <p>
-     * Note that it is safe to call this method any number of times. The original
-     * underlying input stream is closed and discarded only once when this
-     * method is first called.
+     * Note that it is safe to call this method any number of times. The original underlying input stream is closed and discarded only once when this method is
+     * first called.
+     * </p>
      *
      * @throws IOException if the underlying input stream can not be closed
      */
@@ -140,9 +144,9 @@ public void close() throws IOException {
     }
 
     /**
-     * Ensures that the stream is closed before it gets garbage-collected.
-     * As mentioned in {@link #close()}, this is a no-op if the stream has
-     * already been closed.
+     * Ensures that the stream is closed before it gets garbage-collected. As mentioned in {@link #close()}, this is a no-op if the stream has already been
+     * closed.
+     *
      * @throws Throwable if an error occurs
      */
     @Override

src/main/java/org/apache/commons/io/input/BOMInputStream.java

@@ -46,7 +46,7 @@
  * <li>UTF-32LE - {@link ByteOrderMark#UTF_32BE}</li>
  * </ul>
  * <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
  * </p>
  * <h2>Example 1 - Detecting and excluding a UTF-8 BOM</h2>
  *
@@ -89,15 +89,20 @@
  *     // has a UTF-32BE BOM
  * }
  * </pre>
+ * <p>
+ * To build an instance, use {@link Builder}.
+ * </p>
  *
+ * @see Builder
  * @see org.apache.commons.io.ByteOrderMark
  * @see <a href="https://en.wikipedia.org/wiki/Byte_order_mark">Wikipedia - Byte Order Mark</a>
  * @since 2.0
  */
 public class BOMInputStream extends ProxyInputStream {
 
+    // @formatter:off
     /**
-     * Builds a new {@link BOMInputStream} instance.
+     * Builds a new {@link BOMInputStream}.
      *
      * <h2>Using NIO</h2>
      * <pre>{@code
@@ -116,8 +121,10 @@ public class BOMInputStream extends ProxyInputStream {
      *   .get();}
      * </pre>
      *
+     * @see #get()
      * @since 2.12.0
      */
+    // @formatter:on
     public static class Builder extends AbstractStreamBuilder<BOMInputStream, Builder> {
 
         private static final ByteOrderMark[] DEFAULT = { ByteOrderMark.UTF_8 };
@@ -136,13 +143,21 @@ static ByteOrderMark getDefaultByteOrderMark() {
         private boolean include;
 
         /**
-         * Constructs a new instance.
+         * Builds a new {@link BOMInputStream}.
+         * <p>
+         * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
+         * </p>
          * <p>
-         * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+         * This builder use the following aspects: InputStream, OpenOption[], include, and ByteOrderMark[].
          * </p>
          * <p>
-         * This builder use the aspects InputStream, OpenOption[], include, and ByteOrderMark[].
+         * This builder use the following aspects:
          * </p>
+         * <ul>
+         * <li>{@link #getInputStream()}</li>
+         * <li>include}</li>
+         * <li>byteOrderMarks</li>
+         * </ul>
          *
          * @return a new instance.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.

src/main/java/org/apache/commons/io/input/BoundedInputStream.java

@@ -31,32 +31,44 @@
  * doesn't know whether the content hasn't arrived yet or whether the content has finished. So, one of these, initialized with the {@code Content-Length} sent
  * in the {@code ServletInputStream}'s header, will stop it blocking, providing it's been sent with a correct content length.
  * </p>
+ * <p>
+ * To build an instance, use {@link Builder}.
+ * </p>
  *
+ * @see Builder
  * @since 2.0
  */
 public class BoundedInputStream extends ProxyInputStream {
 
     // TODO For 3.0, extend CountingInputStream. Or, add a max feature to CountingInputStream.
 
+    //@formatter:off
     /**
-     * Builds a new {@link BoundedInputStream} instance.
+     * Builds a new {@link BoundedInputStream}.
      *
      * <h2>Using NIO</h2>
-     *
      * <pre>{@code
-     * BoundedInputStream s = BoundedInputStream.builder().setPath(Paths.get("MyFile.xml")).setMaxCount(1024).setPropagateClose(false).get();
+     * BoundedInputStream s = BoundedInputStream.builder()
+     *   .setPath(Paths.get("MyFile.xml"))
+     *   .setMaxCount(1024)
+     *   .setPropagateClose(false)
+     *   .get();
      * }
      * </pre>
-     *
      * <h2>Using IO</h2>
-     *
      * <pre>{@code
-     * BoundedInputStream s = BoundedInputStream.builder().setFile(new File("MyFile.xml")).setMaxCount(1024).setPropagateClose(false).get();
+     * BoundedInputStream s = BoundedInputStream.builder()
+     *   .setFile(new File("MyFile.xml"))
+     *   .setMaxCount(1024)
+     *   .setPropagateClose(false)
+     *   .get();
      * }
      * </pre>
      *
+     * @see #get()
      * @since 2.16.0
      */
+    //@formatter:on
     public static class Builder extends AbstractStreamBuilder<BoundedInputStream, Builder> {
 
         /** The max count of bytes to read. */
@@ -66,10 +78,18 @@ public static class Builder extends AbstractStreamBuilder<BoundedInputStream, Bu
         private boolean propagateClose = true;
 
         /**
-         * Constructs a new instance.
+         * Builds a new {@link BoundedInputStream}.
+         * <p>
+         * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
+         * </p>
          * <p>
-         * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+         * This builder use the following aspects:
          * </p>
+         * <ul>
+         * <li>{@link #getInputStream()}</li>
+         * <li>maxCount</li>
+         * <li>propagateClose</li>
+         * </ul>
          *
          * @return a new instance.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.

src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java

@@ -32,22 +32,24 @@
  * using {@link java.io.BufferedInputStream}. Unfortunately, this is not something already available in JDK, {@code sun.nio.ch.ChannelInputStream} supports
  * reading a file using NIO, but does not support buffering.
  * <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
  * </p>
  * <p>
  * This class was ported and adapted from Apache Spark commit 933dc6cb7b3de1d8ccaf73d124d6eb95b947ed19 where it was called {@code NioBufferedFileInputStream}.
  * </p>
  *
+ * @see Builder
  * @since 2.9.0
  */
 public final class BufferedFileChannelInputStream extends InputStream {
 
+    // @formatter:off
     /**
-     * Builds a new {@link BufferedFileChannelInputStream} instance.
+     * Builds a new {@link BufferedFileChannelInputStream}.
+     *
      * <p>
      * Using File IO:
      * </p>
-     *
      * <pre>{@code
      * BufferedFileChannelInputStream s = BufferedFileChannelInputStream.builder()
      *   .setFile(file)
@@ -57,24 +59,31 @@ public final class BufferedFileChannelInputStream extends InputStream {
      * <p>
      * Using NIO Path:
      * </p>
-     *
      * <pre>{@code
      * BufferedFileChannelInputStream s = BufferedFileChannelInputStream.builder()
      *   .setPath(path)
      *   .setBufferSize(4096)
      *   .get();}
      * </pre>
      *
+     * @see #get()
      * @since 2.12.0
      */
+    // @formatter:on
     public static class Builder extends AbstractStreamBuilder<BufferedFileChannelInputStream, Builder> {
 
         /**
-         * Constructs a new instance.
+         * Builds a new {@link BufferedFileChannelInputStream}.
+         * <p>
+         * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
+         * </p>
          * <p>
-         * You must provide an origin that supports calling {@link #getPath()} and {@link #getBufferSize()} on this builder, otherwise, this method throws an
-         * exception.
+         * This builder use the following aspects:
          * </p>
+         * <ul>
+         * <li>{@link #getInputStream()}</li>
+         * <li>{@link #getBufferSize()}</li>
+         * </ul>
          *
          * @return a new instance.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.