You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@commons.apache.org by "garydgregory (via GitHub)" <gi...@apache.org> on 2023/04/17 12:53:00 UTC
[GitHub] [commons-io] garydgregory commented on a diff in pull request #299: IOUtils clean up javadoc
garydgregory commented on code in PR #299:
URL: https://github.com/apache/commons-io/pull/299#discussion_r1168642577
##########
src/main/java/org/apache/commons/io/IOUtils.java:
##########
@@ -271,109 +276,115 @@ public static BufferedOutputStream buffer(final OutputStream outputStream, final
}
/**
- * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from
- * the given reader.
+ * Returns the given {@link Reader} if it is already a {@link BufferedReader}, otherwise creates a
+ * {@code BufferedReader} from the given {@code Reader}.
*
- * @param reader the reader to wrap or return (not null)
- * @return the given reader or a new {@link BufferedReader} for the given reader
- * @throws NullPointerException if the input parameter is null
+ * @param reader the {@code Reader} to wrap or return (not {@code null}).
+ * @return the given {@code Reader} if it is already an instance of {@code BufferedReader}, or
+ * a new {@code BufferedReader} for the given {@code Reader}.
+ * @throws NullPointerException if the given {@code Reader} is {@code null}.
* @since 2.5
*/
public static BufferedReader buffer(final Reader reader) {
return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader);
}
/**
- * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the
- * given reader.
+ * Returns the given {@link Reader} if it is already a {@link BufferedReader}, otherwise creates a {@code BufferedReader}
+ * from the given {@code Reader}, using the specified buffer size.
*
- * @param reader the reader to wrap or return (not null)
- * @param size the buffer size, if a new BufferedReader is created.
- * @return the given reader or a new {@link BufferedReader} for the given reader
- * @throws NullPointerException if the input parameter is null
+ * @param reader the {@code Reader} to wrap or return (not {@code null}).
+ * @param size the buffer size, if a new {@code BufferedReader} is created.
+ * @return the given {@code Reader} if it is already an instance of {@code BufferedReader}, or
+ * a new {@code BufferedReader} for the given {@code Reader}.
+ * @throws NullPointerException if the given {@code Reader} is {@code null}.
* @since 2.5
*/
public static BufferedReader buffer(final Reader reader, final int size) {
return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size);
}
/**
- * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the
- * given Writer.
+ * Returns the given {@link Writer} if it is already a {@link BufferedWriter}, otherwise creates a {@code BufferedWriter}
+ * from the given {@code Writer}.
*
- * @param writer the Writer to wrap or return (not null)
- * @return the given Writer or a new {@link BufferedWriter} for the given Writer
- * @throws NullPointerException if the input parameter is null
+ * @param writer the {@code Writer} to wrap or return (not {@code null}).
+ * @return the given {@code Writer} if it is already an instance of {@code BufferedWriter}, or
+ * a new {@code BufferedWriter} for the given {@code Writer}.
+ * @throws NullPointerException if the given {@code Writer} is {@code null}.
* @since 2.5
*/
public static BufferedWriter buffer(final Writer writer) {
return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer);
}
/**
- * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the
- * given Writer.
+ * Returns the given {@link Writer} if it is already a {@link BufferedWriter}, otherwise creates a {@code BufferedWriter}
+ * from the given {@code Writer}, using the specified buffer size.
*
- * @param writer the Writer to wrap or return (not null)
- * @param size the buffer size, if a new BufferedWriter is created.
- * @return the given Writer or a new {@link BufferedWriter} for the given Writer
- * @throws NullPointerException if the input parameter is null
+ * @param writer the {@code Writer} to wrap or return (not {@code null}).
+ * @param size the buffer size, if a new {@code BufferedWriter} is created.
+ * @return the given {@code Writer} if it is already an instance of {@code BufferedWriter}, or
+ * a new {@code BufferedWriter} for the given {@code Writer}.
+ * @throws NullPointerException if the given {@code Writer} is {@code null}.
* @since 2.5
*/
public static BufferedWriter buffer(final Writer writer, final int size) {
return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer, size);
}
/**
- * Returns a new byte array of size {@link #DEFAULT_BUFFER_SIZE}.
+ * Returns a new {@code byte[]} array of size {@link #DEFAULT_BUFFER_SIZE}.
*
- * @return a new byte array of size {@link #DEFAULT_BUFFER_SIZE}.
+ * @return a new {@code byte[]} array of size {@link #DEFAULT_BUFFER_SIZE}.
* @since 2.9.0
*/
public static byte[] byteArray() {
return byteArray(DEFAULT_BUFFER_SIZE);
}
/**
- * Returns a new byte array of the given size.
+ * Returns a new {@code byte[]} array of the given size.
*
* TODO Consider guarding or warning against large allocations...
*
* @param size array size.
- * @return a new byte array of the given size.
+ * @return a new {@code byte[]} array of the given size.
* @since 2.9.0
*/
public static byte[] byteArray(final int size) {
return new byte[size];
}
/**
- * Returns a new char array of size {@link #DEFAULT_BUFFER_SIZE}.
+ * Returns a new {@code char[]} array of size {@link #DEFAULT_BUFFER_SIZE}.
Review Comment:
This is no good IMO: "a a new char array" is clear and correct. "a new {@code char} array" would also be correct. BUT "a "new {@code char[]} array" reads like an array of array. So let's pass on this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org