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 1589db4ed Focus Javadoc on current version rather than past versions
(#573)
1589db4ed is described below
commit 1589db4ed21f4262c84f4cd6fb0779b98ee1f388
Author: Elliotte Rusty Harold <elh...@users.noreply.github.com>
AuthorDate: Wed Jan 31 15:28:34 2024 +0000
Focus Javadoc on current version rather than past versions (#573)
* Focus Javadoc on current version rather than past versions
* more from
---
src/main/java/org/apache/commons/io/FileUtils.java | 52 ++++++------------
src/main/java/org/apache/commons/io/IOUtils.java | 64 ++++++----------------
.../commons/io/input/ReversedLinesFileReader.java | 12 +---
3 files changed, 35 insertions(+), 93 deletions(-)
diff --git a/src/main/java/org/apache/commons/io/FileUtils.java
b/src/main/java/org/apache/commons/io/FileUtils.java
index c7bbbdfcb..8101a228e 100644
--- a/src/main/java/org/apache/commons/io/FileUtils.java
+++ b/src/main/java/org/apache/commons/io/FileUtils.java
@@ -2690,8 +2690,7 @@ public class FileUtils {
* @throws NullPointerException if file is {@code null}.
* @throws IOException if an I/O error occurs, including when the file
does not exist, is a directory rather than a
* regular file, or for some other reason why the file cannot be
opened for reading.
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the named charset is
unavailable.
+ * @throws java.nio.charset.UnsupportedCharsetException if the named
charset is unavailable.
* @since 2.3
*/
public static String readFileToString(final File file, final String
charsetName) throws IOException {
@@ -2740,8 +2739,7 @@ public class FileUtils {
* @throws NullPointerException if file is {@code null}.
* @throws IOException if an I/O error occurs, including when the file
does not exist, is a directory rather than a
* regular file, or for some other reason why the file cannot be
opened for reading.
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the named charset is
unavailable.
+ * @throws java.nio.charset.UnsupportedCharsetException if the named
charset is unavailable.
* @since 1.1
*/
public static List<String> readLines(final File file, final String
charsetName) throws IOException {
@@ -3058,11 +3056,8 @@ public class FileUtils {
/**
* Implements behavior similar to the Unix "touch" utility. Creates a new
file with size 0, or, if the file exists, just
- * updates the file's modified time.
- * <p>
- * NOTE: As from v1.3, this method throws an IOException if the last
modified date of the file cannot be set. Also, as
- * from v1.3 this method creates parent directories if they do not exist.
- * </p>
+ * updates the file's modified time. This method throws an IOException if
the last modified date
+ * of the file cannot be set. It creates parent directories if they do not
exist.
*
* @param file the File to touch.
* @throws NullPointerException if the parameter is {@code null}.
@@ -3211,8 +3206,7 @@ public class FileUtils {
* @param append if {@code true}, then the data will be added to the
* end of the file rather than overwriting
* @throws IOException in case of an I/O error
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the encoding is not
supported by the VM
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported by the VM
* @since 2.1
*/
public static void write(final File file, final CharSequence data, final
String charsetName, final boolean append) throws IOException {
@@ -3223,10 +3217,7 @@ public class FileUtils {
/**
* Writes a byte array to a file creating the file if it does not exist.
- * <p>
- * NOTE: As from v1.3, the parent directories of the file will be created
- * if they do not exist.
- * </p>
+ * The parent directories of the file will be created if they do not exist.
*
* @param file the file to write to
* @param data the content to write to the file
@@ -3353,10 +3344,7 @@ public class FileUtils {
* Writes the {@code toString()} value of each item in a collection to
* the specified {@link File} line by line.
* The specified character encoding and the default line ending will be
used.
- * <p>
- * NOTE: As from v1.3, the parent directories of the file will be created
- * if they do not exist.
- * </p>
+ * The parent directories of the file will be created if they do not exist.
*
* @param file the file to write to
* @param charsetName the name of the requested charset, {@code null}
means platform default
@@ -3391,10 +3379,7 @@ public class FileUtils {
* Writes the {@code toString()} value of each item in a collection to
* the specified {@link File} line by line.
* The specified character encoding and the line ending will be used.
- * <p>
- * NOTE: As from v1.3, the parent directories of the file will be created
- * if they do not exist.
- * </p>
+ * The parent directories of the file will be created if they do not exist.
*
* @param file the file to write to
* @param charsetName the name of the requested charset, {@code null}
means platform default
@@ -3461,10 +3446,7 @@ public class FileUtils {
/**
* Writes a String to a file creating the file if it does not exist.
- * <p>
- * NOTE: As from v1.3, the parent directories of the file will be created
- * if they do not exist.
- * </p>
+ * The parent directories of the file will be created if they do not exist.
*
* @param file the file to write
* @param data the content to write to the file
@@ -3478,7 +3460,8 @@ public class FileUtils {
}
/**
- * Writes a String to a file creating the file if it does not exist.
+ * Writes a String to a file, creating the file if it does not exist.
+ * The parent directories of the file are created if they do not exist.
*
* @param file the file to write
* @param data the content to write to the file
@@ -3495,11 +3478,8 @@ public class FileUtils {
}
/**
- * Writes a String to a file creating the file if it does not exist.
- * <p>
- * NOTE: As from v1.3, the parent directories of the file will be created
- * if they do not exist.
- * </p>
+ * Writes a String to a file, creating the file if it does not exist.
+ * The parent directories of the file are created if they do not exist.
*
* @param file the file to write
* @param data the content to write to the file
@@ -3512,7 +3492,8 @@ public class FileUtils {
}
/**
- * Writes a String to a file creating the file if it does not exist.
+ * Writes a String to a file, creating the file if it does not exist.
+ * The parent directories of the file are created if they do not exist.
*
* @param file the file to write
* @param data the content to write to the file
@@ -3520,8 +3501,7 @@ public class FileUtils {
* @param append if {@code true}, then the String will be added to the
* end of the file rather than overwriting
* @throws IOException in case of an I/O error
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the encoding is not
supported by the VM
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported by the VM
* @since 2.1
*/
public static void writeStringToFile(final File file, final String data,
final String charsetName, final boolean append) throws IOException {
diff --git a/src/main/java/org/apache/commons/io/IOUtils.java
b/src/main/java/org/apache/commons/io/IOUtils.java
index 03a2bc246..f24272577 100644
--- a/src/main/java/org/apache/commons/io/IOUtils.java
+++ b/src/main/java/org/apache/commons/io/IOUtils.java
@@ -1175,9 +1175,7 @@ public class IOUtils {
* @param inputCharsetName the name of the requested charset for the
InputStream, null means platform default
* @throws NullPointerException if the input or
output is null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static void copy(final InputStream input, final Writer writer,
final String inputCharsetName)
@@ -1352,9 +1350,7 @@ public class IOUtils {
* @param outputCharsetName the name of the requested charset for the
OutputStream, null means platform default
* @throws NullPointerException if the input or
output is null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static void copy(final Reader reader, final OutputStream output,
final String outputCharsetName)
@@ -1853,9 +1849,7 @@ public class IOUtils {
* @param charsetName the encoding to use, null means platform default
* @return an Iterator of the lines in the reader, never null
* @throws IllegalArgumentException if the input is
null
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.2
*/
public static LineIterator lineIterator(final InputStream input, final
String charsetName) {
@@ -2221,9 +2215,7 @@ public class IOUtils {
* @return the list of Strings, never null
* @throws NullPointerException if the input is
null
* @throws UncheckedIOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static List<String> readLines(final InputStream input, final String
charsetName) throws UncheckedIOException {
@@ -2845,9 +2837,7 @@ public class IOUtils {
* @return the requested byte array
* @throws NullPointerException if the input is
null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static byte[] toByteArray(final Reader reader, final String
charsetName) throws IOException {
@@ -2974,9 +2964,7 @@ public class IOUtils {
* @return the requested character array
* @throws NullPointerException if the input is
null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static char[] toCharArray(final InputStream inputStream, final
String charsetName) throws IOException {
@@ -3040,9 +3028,7 @@ public class IOUtils {
* @param input the CharSequence to convert
* @param charsetName the name of the requested charset, null means
platform default
* @return an input stream
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 2.0
*/
public static InputStream toInputStream(final CharSequence input, final
String charsetName) {
@@ -3087,9 +3073,7 @@ public class IOUtils {
* @param input the string to convert
* @param charsetName the name of the requested charset, null means
platform default
* @return an input stream
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static InputStream toInputStream(final String input, final String
charsetName) {
@@ -3186,9 +3170,7 @@ public class IOUtils {
* @return the requested String
* @throws NullPointerException if the input is
null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
*/
public static String toString(final InputStream input, final String
charsetName)
throws IOException {
@@ -3294,9 +3276,7 @@ public class IOUtils {
* @param charsetName The encoding name for the URL contents.
* @return The contents of the URL as a String.
* @throws IOException if an I/O
exception occurs.
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 2.1
*/
public static String toString(final URI uri, final String charsetName)
throws IOException {
@@ -3337,9 +3317,7 @@ public class IOUtils {
* @param charsetName The encoding name for the URL contents.
* @return The contents of the URL as a String.
* @throws IOException if an I/O
exception occurs.
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 2.1
*/
public static String toString(final URL url, final String charsetName)
throws IOException {
@@ -3421,9 +3399,7 @@ public class IOUtils {
* @param charsetName the name of the requested charset, null means
platform default
* @throws NullPointerException if output is null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static void write(final byte[] data, final Writer writer, final
String charsetName) throws IOException {
@@ -3492,8 +3468,7 @@ public class IOUtils {
* @param charsetName the name of the requested charset, null means
platform default
* @throws NullPointerException if output is null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static void write(final char[] data, final OutputStream output,
final String charsetName)
@@ -3575,8 +3550,7 @@ public class IOUtils {
* @param charsetName the name of the requested charset, null means
platform default
* @throws NullPointerException if output is null
* @throws IOException if an I/O error occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 2.0
*/
public static void write(final CharSequence data, final OutputStream
output, final String charsetName)
@@ -3660,8 +3634,7 @@ public class IOUtils {
* @param charsetName the name of the requested charset, null means
platform default
* @throws NullPointerException if output is null
* @throws IOException if an I/O error occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static void write(final String data, final OutputStream output,
final String charsetName)
@@ -3721,8 +3694,7 @@ public class IOUtils {
* @param charsetName the name of the requested charset, null means
platform default
* @throws NullPointerException if output is null
* @throws IOException if an I/O error occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- * .UnsupportedEncodingException} in version 2.2 if the encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
* @deprecated Use {@link #write(CharSequence, OutputStream, String)}.
*/
@@ -3876,9 +3848,7 @@ public class IOUtils {
* @param charsetName the name of the requested charset, null means
platform default
* @throws NullPointerException if the output is
null
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
{@link java.io
- *
.UnsupportedEncodingException} in version 2.2 if the
- * encoding is not
supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 1.1
*/
public static void writeLines(final Collection<?> lines, final String
lineEnding,
diff --git
a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
index 8fb7ca914..cd883af9a 100644
--- a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
+++ b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
@@ -343,11 +343,7 @@ public class ReversedLinesFileReader implements Closeable {
* system).
* @param charsetName the encoding of the file, null uses the default
Charset.
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
- * {@link
UnsupportedEncodingException}
- * in version 2.2 if
the
- * encoding is not
- * supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @deprecated Use {@link #builder()}, {@link Builder}, and {@link
Builder#get()}
*/
@Deprecated
@@ -448,11 +444,7 @@ public class ReversedLinesFileReader implements Closeable {
* system).
* @param charsetName the encoding of the file, null uses the default
Charset.
* @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException thrown instead of
- * {@link
UnsupportedEncodingException}
- * in version 2.2 if
the
- * encoding is not
- * supported.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
* @since 2.7
* @deprecated Use {@link #builder()}, {@link Builder}, and {@link
Builder#get()}
*/
