[commons-io] branch master updated: Improve `ReaderInputStream` documentation (#291)

[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 8700501  Improve `ReaderInputStream` documentation (#291)
8700501 is described below

commit 8700501e96cda01753587e2ac40ea2db35ff4129
Author: Marcono1234 <Ma...@users.noreply.github.com>
AuthorDate: Mon Feb 7 13:27:20 2022 +0100

    Improve `ReaderInputStream` documentation (#291)
    
    * [IO-715] Mention ReaderInputStream behavior regarding CharsetEncoder.reset()
    
    * [IO-713] Remove incorrect documentation about ReaderInputStream.available()
    
    * (doc) Describe default CodingErrorAction of ReaderInputStream
    
    * (doc) Close <p> tags in ReaderInputStream documentation
    
    * Remove redundant ReaderInputStream.available() override again
---
 .../apache/commons/io/input/ReaderInputStream.java | 35 ++++++++++++++++++++--
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
index f2fb01f..a69182d 100644
--- a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
@@ -70,9 +70,8 @@ import org.apache.commons.io.charset.CharsetEncoders;
  * appear is when implementing the {@code javax.activation.DataSource} interface from the Java Activation Framework.
  * </p>
  * <p>
- * Given the fact that the {@link Reader} class doesn't provide any way to predict whether the next read operation will
- * block or not, it is not possible to provide a meaningful implementation of the {@link InputStream#available()}
- * method. A call to this method will always return 0. Also, this class doesn't support {@link InputStream#mark(int)}.
+ * The {@link #available()} method of this class always returns 0. The methods {@link #mark(int)} and {@link #reset()}
+ * are not supported.
  * </p>
  * <p>
  * Instances of {@link ReaderInputStream} are not thread safe.
@@ -132,6 +131,11 @@ public class ReaderInputStream extends InputStream {
      * Constructs a new {@link ReaderInputStream} with a default input buffer size of {@value #DEFAULT_BUFFER_SIZE}
      * characters.
      *
+     * <p>
+     * The encoder created for the specified charset will use {@link CodingErrorAction#REPLACE} for malformed input
+     * and unmappable characters.
+     * </p>
+     *
      * @param reader the target {@link Reader}
      * @param charset the charset encoding
      */
@@ -142,6 +146,11 @@ public class ReaderInputStream extends InputStream {
     /**
      * Constructs a new {@link ReaderInputStream}.
      *
+     * <p>
+     * The encoder created for the specified charset will use {@link CodingErrorAction#REPLACE} for malformed input
+     * and unmappable characters.
+     * </p>
+     *
      * @param reader the target {@link Reader}.
      * @param charset the charset encoding.
      * @param bufferSize the size of the input buffer in number of characters.
@@ -159,6 +168,11 @@ public class ReaderInputStream extends InputStream {
     /**
      * Constructs a new {@link ReaderInputStream}.
      *
+     * <p>
+     * This constructor does not call {@link CharsetEncoder#reset() reset} on the provided encoder. The caller
+     * of this constructor should do this when providing an encoder which had already been in use.
+     * </p>
+     *
      * @param reader the target {@link Reader}
      * @param charsetEncoder the charset encoder
      * @since 2.1
@@ -170,6 +184,11 @@ public class ReaderInputStream extends InputStream {
     /**
      * Constructs a new {@link ReaderInputStream}.
      *
+     * <p>
+     * This constructor does not call {@link CharsetEncoder#reset() reset} on the provided encoder. The caller
+     * of this constructor should do this when providing an encoder which had already been in use.
+     * </p>
+     *
      * @param reader the target {@link Reader}
      * @param charsetEncoder the charset encoder, null defauls to the default Charset encoder.
      * @param bufferSize the size of the input buffer in number of characters
@@ -188,6 +207,11 @@ public class ReaderInputStream extends InputStream {
      * Constructs a new {@link ReaderInputStream} with a default input buffer size of {@value #DEFAULT_BUFFER_SIZE}
      * characters.
      *
+     * <p>
+     * The encoder created for the specified charset will use {@link CodingErrorAction#REPLACE} for malformed input
+     * and unmappable characters.
+     * </p>
+     *
      * @param reader the target {@link Reader}
      * @param charsetName the name of the charset encoding
      */
@@ -198,6 +222,11 @@ public class ReaderInputStream extends InputStream {
     /**
      * Constructs a new {@link ReaderInputStream}.
      *
+     * <p>
+     * The encoder created for the specified charset will use {@link CodingErrorAction#REPLACE} for malformed input
+     * and unmappable characters.
+     * </p>
+     *
      * @param reader the target {@link Reader}
      * @param charsetName the name of the charset encoding, null maps to the default Charset.
      * @param bufferSize the size of the input buffer in number of characters