(commons-io) branch master updated: Javadoc

[gg...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git


The following commit(s) were added to refs/heads/master by this push:
     new d284ba45b Javadoc
d284ba45b is described below

commit d284ba45b19cc58d25a2bba5f37e382187b70647
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Feb 18 15:30:43 2024 -0500

    Javadoc
---
 .../apache/commons/io/input/ProxyInputStream.java  | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/src/main/java/org/apache/commons/io/input/ProxyInputStream.java b/src/main/java/org/apache/commons/io/input/ProxyInputStream.java
index 872c29144..0d05c9e66 100644
--- a/src/main/java/org/apache/commons/io/input/ProxyInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ProxyInputStream.java
@@ -25,18 +25,20 @@ import java.io.InputStream;
 import org.apache.commons.io.IOUtils;
 
 /**
- * A Proxy stream which acts as expected, that is it passes the method
- * calls on to the proxied stream and doesn't change which methods are
- * being called.
+ * A proxy stream which acts as a {@link FilterInputStream}, by passing all method calls on to the proxied stream, not changing which methods are called.
  * <p>
- * It is an alternative base class to FilterInputStream
- * to increase reusability, because FilterInputStream changes the
- * methods being called, such as read(byte[]) to read(byte[], int, int).
+ * It is an alternative base class to {@link FilterInputStream} to increase reusability, because {@link FilterInputStream} changes the methods being called,
+ * such as read(byte[]) to read(byte[], int, int).
  * </p>
  * <p>
- * See the protected methods for ways in which a subclass can easily decorate
- * a stream with custom pre-, post- or error processing functionality.
+ * In addition, this class allows you to:
  * </p>
+ * <ul>
+ * <li>notify a subclass that <em>n</em> bytes are about to be read through {@link #beforeRead(int)}</li>
+ * <li>notify a subclass that <em>n</em> bytes were read through {@link #afterRead(int)}</li>
+ * <li>notify a subclass that an exception was caught through {@link #handleIOException(IOException)}</li>
+ * <li>{@link #unwrap()} itself</li>
+ * </ul>
  */
 public abstract class ProxyInputStream extends FilterInputStream {
 
@@ -71,7 +73,7 @@ public abstract class ProxyInputStream extends FilterInputStream {
      */
     @SuppressWarnings("unused") // Possibly thrown from subclasses.
     protected void afterRead(final int n) throws IOException {
-        // no-op
+        // no-op default
     }
 
     /**
@@ -112,7 +114,7 @@ public abstract class ProxyInputStream extends FilterInputStream {
      */
     @SuppressWarnings("unused") // Possibly thrown from subclasses.
     protected void beforeRead(final int n) throws IOException {
-        // no-op
+        // no-op default
     }
 
     /**