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
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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
/**
* 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