Javadoc

Author: garydgregory

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

@@ -58,10 +58,11 @@
 import org.apache.commons.io.output.WriterOutputStream;
 
 /**
- * Abstract base class that encapsulates the <em>origin</em> of data used by Commons IO builders.
+ * Abstracts and wraps an <em>origin</em> for builders, where an origin is a {@code byte[]}, {@link Channel}, {@link CharSequence}, {@link File},
+ * {@link InputStream}, {@link IORandomAccessFile}, {@link OutputStream}, {@link Path}, {@link RandomAccessFile}, {@link Reader}, {@link URI},
+ * or {@link Writer}.
  * <p>
- * An origin represents where bytes/characters come from or go to, such as a {@link File}, {@link Path},
- * {@link Reader}, {@link Writer}, {@link InputStream}, {@link OutputStream}, or {@link URI}. Concrete subclasses
+ * An origin represents where bytes/characters come from or go to. Concrete subclasses
  * expose only the operations that make sense for the underlying source or sink; invoking an unsupported operation
  * results in {@link UnsupportedOperationException} (see, for example, {@link #getFile()} and {@link #getPath()}).
  * </p>

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

@@ -43,7 +43,7 @@
 import org.apache.commons.io.build.AbstractOrigin.WriterOrigin;
 
 /**
- * Abstracts building an instance of {@code T}.
+ * Abstracts <em>building</em> an instance of type {@code T} where {@code T} is unbounded from a wrapped {@linkplain AbstractOrigin origin}.
  *
  * @param <T> the type of instances to build.
  * @param <B> the type of builder subclass.

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

@@ -36,7 +36,9 @@
 import org.apache.commons.io.file.PathUtils;
 
 /**
- * Abstracts building a typed instance of {@code T}.
+ * Abstracts <em>building</em> a typed instance of type {@code T} where {@code T} is unbounded. This class contains various properties like a buffer size,
+ * buffer size checker, a buffer size default, buffer size maximum, Charset, Charset default, default size checker, and open options. A subclass may use all,
+ * some, or none of these properties in building instances of {@code T}.
  *
  * @param <T> the type of instances to build.
  * @param <B> the type of builder subclass.

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

@@ -20,7 +20,7 @@
 import org.apache.commons.io.function.IOSupplier;
 
 /**
- * Abstracts supplying an instance of {@code T}.
+ * Abstracts <em>supplying</em> an instance of type {@code T} where {@code T} is unbounded. This class carries no state.
  * <p>
  * Extend this class to implement the builder pattern.
  * </p>
@@ -120,6 +120,7 @@ public void test() {
  *
  * @param <T> the type of instances to build.
  * @param <B> the type of builder subclass.
+ * @see IOSupplier
  * @since 2.12.0
  */
 public abstract class AbstractSupplier<T, B extends AbstractSupplier<T, B>> implements IOSupplier<T> {

src/main/java/org/apache/commons/io/build/package-info.java

@@ -14,10 +14,40 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 /**
- * Provides classes to implement IO builders.
+ * Provides classes to implement the builder pattern for IO classes.
+ *
+ * <p>
+ * The main classes in this package are (indentation reflects hierarchy):
+ * </p>
+ * <ul>
+ * <li>The root class {@linkplain org.apache.commons.io.build.AbstractSupplier AbstractSupplier} abstracts <em>supplying</em> an instance of type {@code T}
+ * where {@code T} is unbounded. This class carries no state.
+ * <ul>
+ *
+ * <li>{@linkplain org.apache.commons.io.build.AbstractOrigin AbstractOrigin} extends {@linkplain org.apache.commons.io.build.AbstractSupplier AbstractSupplier}
+ * to abstract and wrap an <em>origin</em> for builders, where an origin is a {@code byte[]}, {@linkplain java.nio.channels.Channel Channel},
+ * {@linkplain java.lang.CharSequence CharSequence}, {@linkplain java.io.File File}, {@linkplain java.io.InputStream InputStream},
+ * {@linkplain org.apache.commons.io.IORandomAccessFile IORandomAccessFile}, {@linkplain java.io.OutputStream OutputStream}, {@linkplain java.nio.file.Path
+ * Path}, {@linkplain java.io.RandomAccessFile RandomAccessFile}, {@linkplain java.io.Reader Reader}, {@linkplain java.net.URI URI}, or
+ * {@linkplain java.io.Writer Writer}.</li>
+ *
+ * <li>{@linkplain org.apache.commons.io.build.AbstractOriginSupplier AbstractOriginSupplier} extends {@linkplain org.apache.commons.io.build.AbstractSupplier
+ * AbstractSupplier} to abstract <em>building</em> an instance of type {@code T} where {@code T} is unbounded from a wrapped
+ * {@linkplain org.apache.commons.io.build.AbstractOrigin origin}.
+ *
+ * <ul>
+ * <li>{@linkplain org.apache.commons.io.build.AbstractStreamBuilder AbstractStreamBuilder} extends
+ * {@linkplain org.apache.commons.io.build.AbstractOriginSupplier AbstractOriginSupplier} to abstract <em>building</em> a typed instance of type {@code T} where
+ * {@code T} is unbounded. This class contains various properties like a buffer size, buffer size checker, a buffer size default, buffer size maximum, Charset,
+ * Charset default, default size checker, and open options. A subclass may use all, some, or none of these properties in building instances of {@code T}.</li>
+ * </ul>
+ * </li>
+ * </ul>
+ * </li>
+ * </ul>
  *
  * @since 2.12.0
  */
+
 package org.apache.commons.io.build;