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()} */