Javadoc and inline comments

- Clarify text, id est, 'i.e.' isn't needed
- Remove obsolete Java 1.4 comment

Author: garydgregory

src/main/java/org/apache/commons/io/FileUtils.java

@@ -209,7 +209,7 @@ public class FileUtils {
     /**
      * Returns a human-readable version of the file size, where the input represents a specific number of bytes.
      * <p>
-     * If the size is over 1GB, the size is returned as the number of whole GB, i.e. the size is rounded down to the
+     * If the size is over 1GB, the size is returned as the number of whole GB, the size is rounded down to the
      * nearest GB boundary.
      * </p>
      * <p>
@@ -248,7 +248,7 @@ public static String byteCountToDisplaySize(final BigInteger size) {
     /**
      * Returns a human-readable version of the file size, where the input represents a specific number of bytes.
      * <p>
-     * If the size is over 1GB, the size is returned as the number of whole GB, i.e. the size is rounded down to the
+     * If the size is over 1GB, the size is returned as the number of whole GB, the size is rounded down to the
      * nearest GB boundary.
      * </p>
      * <p>
@@ -267,7 +267,7 @@ public static String byteCountToDisplaySize(final long size) {
     /**
      * Returns a human-readable version of the file size, where the input represents a specific number of bytes.
      * <p>
-     * If the size is over 1GB, the size is returned as the number of whole GB, i.e. the size is rounded down to the
+     * If the size is over 1GB, the size is returned as the number of whole GB, the size is rounded down to the
      * nearest GB boundary.
      * </p>
      * <p>
@@ -1167,7 +1167,7 @@ public static File current() {
     }
 
     /**
-     * Decodes the specified URL as per RFC 3986, i.e. transforms
+     * Decodes the specified URL as per RFC 3986, transforming
      * percent-encoded octets to characters by decoding with the UTF-8 character
      * set. This function is primarily intended for usage with
      * {@link java.net.URL} which unfortunately does not enforce proper URLs. As

src/main/java/org/apache/commons/io/comparator/CompositeFileComparator.java

@@ -28,7 +28,7 @@
  * <p>
  * This comparator can be used to sort lists or arrays of files by combining a number of other comparators.
  * <p>
- * Example of sorting a list of files by type (i.e. directory or file) and then by name:
+ * Example of sorting a list of files by type (directory or file) and then by name:
  *
  * <pre>
  *       CompositeFileComparator comparator = new CompositeFileComparator(

src/main/java/org/apache/commons/io/comparator/ReverseFileComparator.java

@@ -49,8 +49,8 @@ public ReverseFileComparator(final Comparator<File> delegate) {
      *
      * @param file1 The first file to compare.
      * @param file2 The second file to compare.
-     * @return the result from the delegate {@link Comparator#compare(Object, Object)} reversing the value (i.e.
-     *         positive becomes negative and vice versa).
+     * @return the result from the delegate {@link Comparator#compare(Object, Object)} reversing the value,
+     *         positive becomes negative and vice versa.
      */
     @Override
     public int compare(final File file1, final File file2) {

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

@@ -42,7 +42,7 @@
  * to compare (and sort lists or arrays of files) by combining a number of other comparators.
  * </p>
  * <p>
- * For example, to sort an array of files by type (i.e. directory or file)
+ * For example, to sort an array of files by type (directory or file)
  * and then by name:
  * </p>
  * <pre>

src/main/java/org/apache/commons/io/filefilter/HiddenFileFilter.java

@@ -40,7 +40,7 @@
  *
  * <p>
  * Example, showing how to print out a list of the
- * current directory's <em>visible</em> (i.e. not hidden) files:
+ * current directory's <em>visible</em> (not hidden) files:
  * </p>
  *
  * <pre>

src/main/java/org/apache/commons/io/input/ReaderInputStream.java

@@ -71,7 +71,7 @@
  * <p>
  * Note that while there are use cases where there is no alternative to using this class, very often the need to use this class is an indication of a flaw in
  * the design of the code. This class is typically used in situations where an existing API only accepts an {@link InputStream}, but where the most natural way
- * to produce the data is as a character stream, i.e. by providing a {@link Reader} instance. An example of a situation where this problem may appear is when
+ * to produce the data is as a character stream, by providing a {@link Reader} instance. An example of a situation where this problem may appear is when
  * implementing the {@code javax.activation.DataSource} interface from the Java Activation Framework.
  * </p>
  * <p>

src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java

@@ -178,7 +178,7 @@ private static int requireNonNegative(final int value, final String name) {
     /**
      * End Of Data.
      *
-     * Similar to data.length, i.e. the last readable offset + 1.
+     * Similar to data.length, which is the last readable offset + 1.
      */
     private final int eod;
 

src/main/java/org/apache/commons/io/output/ChunkedWriter.java

@@ -32,7 +32,7 @@
 public class ChunkedWriter extends FilterWriter {
 
     /**
-     * The default chunk size to use, i.e. {@value} bytes.
+     * The default chunk size to use: {@value} bytes.
      */
     private static final int DEFAULT_CHUNK_SIZE = IOUtils.DEFAULT_BUFFER_SIZE;
 

src/main/java/org/apache/commons/io/output/StringBuilderWriter.java

@@ -23,16 +23,14 @@
 /**
  * {@link Writer} implementation that outputs to a {@link StringBuilder}.
  * <p>
- * <strong>NOTE:</strong> This implementation, as an alternative to
- * {@link StringWriter}, provides an <em>un-synchronized</em>
- * (i.e. for use in a single thread) implementation for better performance.
- * For safe usage with multiple {@link Thread}s then
- * {@link StringWriter} should be used.
+ * <strong>NOTE:</strong> This implementation, as an alternative to {@link StringWriter}, provides an <em>un-synchronized</em> implementation for better
+ * performance for use in a single thread. For safe usage with multiple {@link Thread}s, a {@link StringWriter} should be used.
  * </p>
  * <h2>Deprecating Serialization</h2>
  * <p>
  * <em>Serialization is deprecated and will be removed in 3.0.</em>
  * </p>
+ *
  * @since 2.0
  */
 public class StringBuilderWriter extends Writer implements Serializable {

src/main/java/org/apache/commons/io/output/WriterOutputStream.java

@@ -166,12 +166,12 @@ public Builder setCharsetDecoder(final CharsetDecoder charsetDecoder) {
         }
 
         /**
-         * Sets whether the output buffer will be flushed after each write operation ({@code true}), i.e. all available data will be written to the underlying
-         * {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when {@link #flush()} or {@link #close()}
-         * is called.
+         * Sets whether the output buffer will be flushed after each write operation ({@code true}), meaning all available data will be written to the
+         * underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when {@link #flush()} or
+         * {@link #close()} is called.
          *
-         * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
-         *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
+         * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, meaning all available data will be written to
+         *                         the underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
          *                         {@link #flush()} or {@link #close()} is called.
          * @return {@code this} instance.
          */
@@ -275,7 +275,7 @@ public WriterOutputStream(final Writer writer, final Charset charset) {
      * @param writer           the target {@link Writer}
      * @param charset          the charset encoding
      * @param bufferSize       the size of the output buffer in number of characters
-     * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
+     * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, meaning all available data will be written to the
      *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
      *                         {@link #flush()} or {@link #close()} is called.
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
@@ -313,7 +313,7 @@ public WriterOutputStream(final Writer writer, final CharsetDecoder decoder) {
      * @param writer           the target {@link Writer}
      * @param decoder          the charset decoder
      * @param bufferSize       the size of the output buffer in number of characters
-     * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
+     * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, meaning all available data will be written to the
      *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
      *                         {@link #flush()} or {@link #close()} is called.
      * @since 2.1
@@ -347,7 +347,7 @@ public WriterOutputStream(final Writer writer, final String charsetName) {
      * @param writer           the target {@link Writer}
      * @param charsetName      the name of the charset encoding
      * @param bufferSize       the size of the output buffer in number of characters
-     * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
+     * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, meaning all available data will be written to the
      *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
      *                         {@link #flush()} or {@link #close()} is called.
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}