Javadoc improvements

garydgregory · garydgregory · commit 1bdbb60ddb88 · 2025-02-14T08:18:17.000-05:00
diff --git a/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java b/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
@@ -108,14 +108,14 @@ public Builder() {
          * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link #getPath()}</li>
+         * <li>{@link #getPath()} gets the target aspect.</li>
          * <li>{@link #getBufferSize()}</li>
          * </ul>
          *
          * @return a new instance.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.
          * @throws UnsupportedOperationException if the origin cannot be converted to a {@link Path}.
-         * @throws IOException                   if an I/O error occurs.
+         * @throws IOException                   if an I/O error occurs converting to an {@link Path} using {@link #getPath()}.
          * @see #getPath()
          * @see #getBufferSize()
          * @see #getUnchecked()
diff --git a/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java b/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
@@ -77,15 +77,16 @@ public Builder() {
          * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link RandomAccessFile}</li>
+         * <li>{@link RandomAccessFile} gets the target aspect.</li>
          * <li>{@link File}</li>
          * <li>closeOnClose</li>
          * </ul>
          *
          * @return a new instance.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.
          * @throws IllegalStateException         if both RandomAccessFile and origin are set.
-         * @throws UnsupportedOperationException if the origin cannot be converted to a {@link File}.
+         * @throws UnsupportedOperationException if the origin cannot be converted to a {@link RandomAccessFile}.
+         * @throws IOException                   if an I/O error occurs converting to an {@link RandomAccessFile} using {@link #getRandomAccessFile()}.
          * @see AbstractOrigin#getFile()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
@@ -87,15 +87,15 @@ public Builder() {
          * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link #getInputStream()}</li>
+         * <li>{@link #getInputStream()} gets the target aspect.</li>
          * <li>{@link #getBufferSize()}</li>
          * <li>{@link ExecutorService}</li>
          * </ul>
          *
          * @return a new instance.
          * @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.
+         * @throws IOException                   if an I/O error occurs converting to an {@link InputStream} using {@link #getInputStream()}.
          * @see #getInputStream()
          * @see #getBufferSize()
          * @see #getUnchecked()
diff --git a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
@@ -126,15 +126,16 @@ public Builder() {
          * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link #getReader()}</li>
+         * <li>{@link #getReader()} gets the target aspect.</li>
          * <li>{@link #getBufferSize()}</li>
          * <li>{@link #getCharset()}</li>
          * <li>{@link CharsetEncoder}</li>
          * </ul>
          *
          * @return a new instance.
-         * @throws UnsupportedOperationException if the origin cannot provide a Reader.
-         * @throws IllegalStateException if the {@code origin} is {@code null}.
+         * @throws UnsupportedOperationException if the origin cannot provide a {@link Reader}.
+         * @throws IllegalStateException         if the {@code origin} is {@code null}.
+         * @throws IOException                   if an I/O error occurs converting to a {@link Reader} using {@link #getReader()}.
          * @see #getReader()
          * @see CharsetEncoder
          * @see #getBufferSize()
diff --git a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
@@ -104,15 +104,15 @@ public Builder() {
          * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link #getInputStream()}</li>
+         * <li>{@link #getPath()} gets the target aspect.</li>
          * <li>{@link #getBufferSize()}</li>
          * <li>{@link #getCharset()}</li>
          * </ul>
          *
          * @return a new instance.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.
          * @throws UnsupportedOperationException if the origin cannot be converted to a {@link Path}.
-         * @throws IOException                   if an I/O error occurs.
+         * @throws IOException                   if an I/O error occurs converting to a {@link Path} using {@link #getPath()}.
          * @see #getPath()
          * @see #getBufferSize()
          * @see #getCharset()
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java b/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
@@ -87,17 +87,18 @@ public Builder() {
          * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link #getReader()}</li>
+         * <li>{@link #getReader()} gets the target aspect.</li>
          * <li>{@link #getBufferSize()}</li>
          * </ul>
          *
          * @return a new instance.
-         * @throws UnsupportedOperationException if the origin cannot provide a Reader.
+         * @throws UnsupportedOperationException if the origin cannot provide a {@link Reader}.
          * @throws IllegalStateException if the {@code origin} is {@code null}.
          * @see #getReader()
          * @see #getBufferSize()
          * @see #getUnchecked()
          */
+        @SuppressWarnings("resource")
         @Override
         public UncheckedBufferedReader get() {
             // This an unchecked class, so this method is as well.
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java b/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java
@@ -82,14 +82,15 @@ public Builder() {
          * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link #getInputStream()}</li>
+         * <li>{@link #getInputStream()} gets the target aspect.</li>
          * </ul>
          *
          * @return a new instance.
-         * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+         * @throws UnsupportedOperationException if the origin cannot provide an {@link #getInputStream()}.
          * @see #getInputStream()
          * @see #getUnchecked()
          */
+        @SuppressWarnings("resource")
         @Override
         public UncheckedFilterInputStream get() {
             // This an unchecked class, so this method is as well.
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java b/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
@@ -86,11 +86,12 @@ public Builder() {
          * </ul>
          *
          * @return a new instance.
-         * @throws UnsupportedOperationException if the origin cannot provide a Reader.
+         * @throws UnsupportedOperationException if the origin cannot provide a {@link Reader}.
          * @throws IllegalStateException if the {@code origin} is {@code null}.
          * @see #getReader()
          * @see #getUnchecked()
          */
+        @SuppressWarnings("resource")
         @Override
         public UncheckedFilterReader get() {
             // This an unchecked class, so this method is as well.
diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
@@ -106,7 +106,7 @@ public Builder() {
          * @return a new instance.
          * @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.
+         * @throws IOException                   if an I/O error occurs converting to an {@link InputStream} using {@link #getInputStream()}.
          * @see #getInputStream()
          * @see #getBufferSize()
          * @see #getUnchecked()
diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
@@ -106,8 +106,9 @@ public Builder() {
          * </ul>
          *
          * @return a new instance.
-         * @throws UnsupportedOperationException if the origin cannot provide a byte[].
+         * @throws UnsupportedOperationException if the origin cannot provide a {@code byte[]}.
          * @throws IllegalStateException         if the {@code origin} is {@code null}.
+         * @throws IOException                   if an I/O error occurs converting to an {@code byte[]} using {@link AbstractOrigin#getByteArray()}.
          * @see AbstractOrigin#getByteArray()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
@@ -92,7 +92,7 @@ public Builder() {
          * @return a new instance.
          * @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.
+         * @throws IOException                   if an I/O error occurs converting to an {@link InputStream} using {@link #getInputStream()}.
          * @see #getInputStream()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
@@ -148,7 +148,7 @@ public Builder() {
          * @return a new instance.
          * @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.
+         * @throws IOException                   if an I/O error occurs converting to an {@link InputStream} using {@link #getInputStream()}.
          * @throws XmlStreamReaderException thrown if the Charset encoding could not be determined according to the specification.
          * @see #getInputStream()
          * @see #getUnchecked()
diff --git a/src/main/java/org/apache/commons/io/monitor/FileAlterationObserver.java b/src/main/java/org/apache/commons/io/monitor/FileAlterationObserver.java
@@ -30,6 +30,7 @@
 
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOCase;
+import org.apache.commons.io.build.AbstractOrigin;
 import org.apache.commons.io.build.AbstractOriginSupplier;
 import org.apache.commons.io.comparator.NameFileComparator;
 import org.apache.commons.io.filefilter.TrueFileFilter;
@@ -144,6 +145,7 @@ private Builder() {
         /**
          * Gets a new {@link FileAlterationObserver} instance.
          *
+         * @throws IOException                   if an I/O error occurs converting to an {@link File} using {@link AbstractOrigin#getFile()}.
          * @see #getUnchecked()
          */
         @Override
diff --git a/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java b/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java
@@ -74,7 +74,7 @@ public Builder() {
         /**
          * Builds a new {@link UnsynchronizedByteArrayOutputStream}.
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getOutputStream()} is the target aspect.</li>
diff --git a/src/main/java/org/apache/commons/io/output/DeferredFileOutputStream.java b/src/main/java/org/apache/commons/io/output/DeferredFileOutputStream.java
@@ -94,7 +94,7 @@ public Builder() {
         /**
          * Builds a new {@link DeferredFileOutputStream}.
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getBufferSize()}</li>
diff --git a/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java b/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
@@ -100,7 +100,7 @@ public Builder() {
          * You must set an aspect that supports {@link File} on this builder, otherwise, this method throws an exception.
          * </p>
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link File} is the target aspect.</li>
diff --git a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
@@ -90,18 +90,19 @@ public Builder() {
          * You must set an aspect that supports {@link File} on this builder, otherwise, this method throws an exception.
          * </p>
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link File}</li>
+         * <li>{@link File} is the target aspect.</li>
          * <li>{@link #getCharset()}</li>
          * <li>append</li>
          * <li>lockDirectory</li>
          * </ul>
          *
          * @return a new instance.
          * @throws UnsupportedOperationException if the origin cannot provide a File.
-         * @throws IllegalStateException if the {@code origin} is {@code null}.
+         * @throws IllegalStateException         if the {@code origin} is {@code null}.
+         * @throws IOException                   if an I/O error occurs converting to an {@link File} using {@link #getFile()}.
          * @see AbstractOrigin#getFile()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/output/ProxyOutputStream.java b/src/main/java/org/apache/commons/io/output/ProxyOutputStream.java
@@ -55,16 +55,16 @@ public Builder() {
         /**
          * Builds a new {@link ProxyOutputStream}.
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
-         * <li>{@link #getOutputStream()}</li>
+         * <li>{@link #getOutputStream()} is the target aspect.</li>
          * </ul>
          *
          * @return a new instance.
          * @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.
+         * @throws IOException                   if an I/O error occurs converting to an {@link OutputStream} using {@link #getOutputStream()}.
          * @see #getOutputStream()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/output/RandomAccessFileOutputStream.java b/src/main/java/org/apache/commons/io/output/RandomAccessFileOutputStream.java
@@ -17,12 +17,14 @@
 
 package org.apache.commons.io.output;
 
+import java.io.File;
 import java.io.IOException;
 import java.io.OutputStream;
 import java.io.RandomAccessFile;
 import java.nio.file.StandardOpenOption;
 import java.util.Objects;
 
+import org.apache.commons.io.build.AbstractOrigin;
 import org.apache.commons.io.build.AbstractStreamBuilder;
 
 /**
@@ -60,6 +62,29 @@ private Builder() {
             setOpenOptions(StandardOpenOption.WRITE);
         }
 
+        /**
+         * Builds a new {@link RandomAccessFileOutputStream}.
+         * <p>
+         * You must set an aspect that supports {@link RandomAccessFile} or {@link File}, otherwise, this method throws an exception. Only set one of
+         * RandomAccessFile or an origin that can be converted to a File.
+         * </p>
+         * <p>
+         * This builder uses the following aspects:
+         * </p>
+         * <ul>
+         * <li>{@link RandomAccessFile} is the target aspect.</li>
+         * <li>{@link File}</li>
+         * <li>closeOnClose</li>
+         * </ul>
+         *
+         * @return a new instance.
+         * @throws IllegalStateException         if the {@code origin} is {@code null}.
+         * @throws IllegalStateException         if both RandomAccessFile and origin are set.
+         * @throws UnsupportedOperationException if the origin cannot be converted to a {@link RandomAccessFile}.
+         * @throws IOException                   if an I/O error occurs converting to an {@link RandomAccessFile} using {@link #getRandomAccessFile()}.
+         * @see AbstractOrigin#getFile()
+         * @see #getUnchecked()
+         */
         @Override
         public RandomAccessFileOutputStream get() throws IOException {
             return new RandomAccessFileOutputStream(getRandomAccessFile());
diff --git a/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java b/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
@@ -77,7 +77,7 @@ public Builder() {
          * You must set an aspect that supports {@link #getOutputStream()} on this builder, otherwise, this method throws an exception.
          * </p>
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getOutputStream()}</li>
@@ -86,7 +86,7 @@ public Builder() {
          * @return a new instance.
          * @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.
+         * @throws IOException                   if an I/O error occurs converting to an {@link OutputStream} using {@link #getOutputStream()}.
          * @see #getOutputStream()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java b/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
@@ -78,14 +78,15 @@ public Builder() {
          * You must set an aspect that supports {@link #getWriter()} on this builder, otherwise, this method throws an exception.
          * </p>
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getWriter()}</li>
          * </ul>
          *
          * @return a new instance.
-         * @throws UnsupportedOperationException if the origin cannot provide a Writer.
+         * @throws UnsupportedOperationException if the origin cannot provide a {@link Writer}.
+         * @throws IOException                   if an I/O error occurs converting to an {@link Writer} using {@link #getWriter()}.
          * @see #getWriter()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java b/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
@@ -75,7 +75,7 @@ public Builder() {
          * Builds a new {@link UnsynchronizedByteArrayOutputStream}.
          *
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getBufferSize()}</li>
diff --git a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
@@ -120,7 +120,7 @@ public Builder() {
          * You must set an aspect that supports {@link #getWriter()} on this builder, otherwise, this method throws an exception.
          * </p>
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getWriter()}</li>
@@ -130,7 +130,8 @@ public Builder() {
          * </ul>
          *
          * @return a new instance.
-         * @throws UnsupportedOperationException if the origin cannot provide a Writer.
+         * @throws UnsupportedOperationException if the origin cannot provide a {@link Writer}.
+         * @throws IOException                   if an I/O error occurs converting to an {@link Writer} using {@link #getWriter()}.
          * @see #getWriter()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java b/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
@@ -81,7 +81,7 @@ public Builder() {
          * You must set an aspect that supports {@link #getOutputStream()} on this builder, otherwise, this method throws an exception.
          * </p>
          * <p>
-         * This builder use the following aspects:
+         * This builder uses the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getOutputStream()}</li>
@@ -91,7 +91,7 @@ public Builder() {
          * @return a new instance.
          * @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.
+         * @throws IOException                   if an I/O error occurs converting to an {@link OutputStream} using {@link #getOutputStream()}.
          * @see #getOutputStream()
          * @see #getUnchecked()
          */
diff --git a/src/main/java/org/apache/commons/io/serialization/ValidatingObjectInputStream.java b/src/main/java/org/apache/commons/io/serialization/ValidatingObjectInputStream.java
