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

Author: Marcono1234

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 @@ public ReaderInputStream(final Reader reader) {
      * 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 ReaderInputStream(final Reader reader, final Charset charset) {
     /**
      * 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 ReaderInputStream(final Reader reader, final Charset charset, final int b
     /**
      * 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 ReaderInputStream(final Reader reader, final CharsetEncoder charsetEncode
     /**
      * 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 ReaderInputStream(final Reader reader, final CharsetEncoder charsetEncode
      * 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 ReaderInputStream(final Reader reader, final String charsetName) {
     /**
      * 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