You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by gg...@apache.org on 2007/01/01 23:45:49 UTC
svn commit: r491668 -
/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
Author: ggregory
Date: Mon Jan 1 14:45:49 2007
New Revision: 491668
URL: http://svn.apache.org/viewvc?view=rev&rev=491668
Log:
Add missing Javadoc tags. Use "null" is code format (<code>null</code>)
Modified:
jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
Modified: jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java?view=diff&rev=491668&r1=491667&r2=491668
==============================================================================
--- jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java (original)
+++ jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java Mon Jan 1 14:45:49 2007
@@ -117,7 +117,8 @@
* An exception is thrown if the file object exists but is a directory.
* An exception is thrown if the file exists but cannot be read.
*
- * @param file the file to open for input, not null
+ * @param file the file to open for input, must not be <code>null</code>
+ * @return a new {@link FileInputStream} for the specified file
* @throws FileNotFoundException if the file does not exist
* @throws IOException if the file object is a directory
* @throws IOException if the file cannot be read
@@ -151,7 +152,8 @@
* An exception is thrown if the file exists but cannot be written to.
* An exception is thrown if the parent directory cannot be created.
*
- * @param file the file to open for output, not null
+ * @param file the file to open for output, must not be <code>null</code>
+ * @return a new {@link FileOutputStream} for the specified file
* @throws IOException if the file object is a directory
* @throws IOException if the file cannot be written to
* @throws IOException if a parent directory needs creating but that fails
@@ -278,7 +280,7 @@
* @param directory the directory to search in
* @param fileFilter filter to apply when finding files.
* @param dirFilter optional filter to apply when finding subdirectories.
- * If this parameter is null, subdirectories will not be included in the
+ * If this parameter is <code>null</code>, subdirectories will not be included in the
* search. Use TrueFileFilter.INSTANCE to match all directories.
* @return an collection of java.io.File with the matching files
* @see org.apache.commons.io.filefilter.FileFilterUtils
@@ -324,7 +326,7 @@
* @param directory the directory to search in
* @param fileFilter filter to apply when finding files.
* @param dirFilter optional filter to apply when finding subdirectories.
- * If this parameter is null, subdirectories will not be included in the
+ * If this parameter is <code>null</code>, subdirectories will not be included in the
* search. Use TrueFileFilter.INSTANCE to match all directories.
* @return an iterator of java.io.File for the matching files
* @see org.apache.commons.io.filefilter.FileFilterUtils
@@ -359,7 +361,7 @@
*
* @param directory the directory to search in
* @param extensions an array of extensions, ex. {"java","xml"}. If this
- * parameter is null, all files are returned.
+ * parameter is <code>null</code>, all files are returned.
* @param recursive if true all subdirectories are searched as well
* @return an collection of java.io.File with the matching files
*/
@@ -383,7 +385,7 @@
*
* @param directory the directory to search in
* @param extensions an array of extensions, ex. {"java","xml"}. If this
- * parameter is null, all files are returned.
+ * parameter is <code>null</code>, all files are returned.
* @param recursive if true all subdirectories are searched as well
* @return an iterator of java.io.File with the matching files
* @since Commons IO 1.2
@@ -456,7 +458,7 @@
* Syntax such as <code>file:///my%20docs/file.txt</code> will be
* correctly decoded to <code>/my docs/file.txt</code>.
*
- * @param url the file URL to convert, null returns null
+ * @param url the file URL to convert, <code>null</code> returns <code>null</code>
* @return the equivalent <code>File</code> object, or <code>null</code>
* if the URL's protocol is not <code>file</code>
* @throws IllegalArgumentException if the file is incorrectly encoded
@@ -482,17 +484,17 @@
* Converts each of an array of <code>URL</code> to a <code>File</code>.
* <p>
* Returns an array of the same size as the input.
- * If the input is null, an empty array is returned.
- * If the input contains null, the output array contains null at the same
+ * If the input is <code>null</code>, an empty array is returned.
+ * If the input contains <code>null</code>, the output array contains <code>null</code> at the same
* index.
* <p>
* This method will decode the URL.
* Syntax such as <code>file:///my%20docs/file.txt</code> will be
* correctly decoded to <code>/my docs/file.txt</code>.
*
- * @param urls the file URLs to convert, null returns empty array
- * @return a non-null array of Files matching the input, with a null item
- * if there was a null at that index in the input array
+ * @param urls the file URLs to convert, <code>null</code> returns empty array
+ * @return a non-<code>null</code> array of Files matching the input, with a <code>null</code> item
+ * if there was a <code>null</code> at that index in the input array
* @throws IllegalArgumentException if any file is not a URL file
* @throws IllegalArgumentException if any file is incorrectly encoded
* @since Commons IO 1.1
@@ -543,8 +545,8 @@
* The destination directory is created if it does not exist.
* If the destination file exists, then this method will overwrite it.
*
- * @param srcFile an existing file to copy, must not be null
- * @param destDir the directory to place the copy in, must not be null
+ * @param srcFile an existing file to copy, must not be <code>null</code>
+ * @param destDir the directory to place the copy in, must not be <code>null</code>
*
* @throws NullPointerException if source or destination is null
* @throws IOException if source or destination is invalid
@@ -563,12 +565,12 @@
* The destination directory is created if it does not exist.
* If the destination file exists, then this method will overwrite it.
*
- * @param srcFile an existing file to copy, must not be null
- * @param destDir the directory to place the copy in, must not be null
+ * @param srcFile an existing file to copy, must not be <code>null</code>
+ * @param destDir the directory to place the copy in, must not be <code>null</code>
* @param preserveFileDate true if the file date of the copy
* should be the same as the original
*
- * @throws NullPointerException if source or destination is null
+ * @throws NullPointerException if source or destination is <code>null</code>
* @throws IOException if source or destination is invalid
* @throws IOException if an IO error occurs during copying
* @see #copyFile(File, File, boolean)
@@ -592,10 +594,10 @@
* created if it does not exist. If the destination file exists, then this
* method will overwrite it.
*
- * @param srcFile an existing file to copy, must not be null
- * @param destFile the new file, must not be null
+ * @param srcFile an existing file to copy, must not be <code>null</code>
+ * @param destFile the new file, must not be <code>null</code>
*
- * @throws NullPointerException if source or destination is null
+ * @throws NullPointerException if source or destination is <code>null</code>
* @throws IOException if source or destination is invalid
* @throws IOException if an IO error occurs during copying
* @see #copyFileToDirectory(File, File)
@@ -612,12 +614,12 @@
* The directory holding the destination file is created if it does not exist.
* If the destination file exists, then this method will overwrite it.
*
- * @param srcFile an existing file to copy, must not be null
- * @param destFile the new file, must not be null
+ * @param srcFile an existing file to copy, must not be <code>null</code>
+ * @param destFile the new file, must not be <code>null</code>
* @param preserveFileDate true if the file date of the copy
* should be the same as the original
*
- * @throws NullPointerException if source or destination is null
+ * @throws NullPointerException if source or destination is <code>null</code>
* @throws IOException if source or destination is invalid
* @throws IOException if an IO error occurs during copying
* @see #copyFileToDirectory(File, File, boolean)
@@ -653,8 +655,8 @@
/**
* Internal copy file method.
*
- * @param srcFile the validated source file, not null
- * @param destFile the validated destination file, not null
+ * @param srcFile the validated source file, must not be <code>null</code>
+ * @param destFile the validated destination file, must not be <code>null</code>
* @param preserveFileDate whether to preserve the file date
* @throws IOException if an error occurs
*/
@@ -695,10 +697,10 @@
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
*
- * @param srcDir an existing directory to copy, must not be null
- * @param destDir the directory to place the copy in, must not be null
+ * @param srcDir an existing directory to copy, must not be <code>null</code>
+ * @param destDir the directory to place the copy in, must not be <code>null</code>
*
- * @throws NullPointerException if source or destination is null
+ * @throws NullPointerException if source or destination is <code>null</code>
* @throws IOException if source or destination is invalid
* @throws IOException if an IO error occurs during copying
* @since Commons IO 1.2
@@ -730,10 +732,10 @@
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
*
- * @param srcDir an existing directory to copy, must not be null
- * @param destDir the new directory, must not be null
+ * @param srcDir an existing directory to copy, must not be <code>null</code>
+ * @param destDir the new directory, must not be <code>null</code>
*
- * @throws NullPointerException if source or destination is null
+ * @throws NullPointerException if source or destination is <code>null</code>
* @throws IOException if source or destination is invalid
* @throws IOException if an IO error occurs during copying
* @since Commons IO 1.1
@@ -752,12 +754,12 @@
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
*
- * @param srcDir an existing directory to copy, must not be null
- * @param destDir the new directory, must not be null
+ * @param srcDir an existing directory to copy, must not be <code>null</code>
+ * @param destDir the new directory, must not be <code>null</code>
* @param preserveFileDate true if the file date of the copy
* should be the same as the original
*
- * @throws NullPointerException if source or destination is null
+ * @throws NullPointerException if source or destination is <code>null</code>
* @throws IOException if source or destination is invalid
* @throws IOException if an IO error occurs during copying
* @since Commons IO 1.1
@@ -785,8 +787,8 @@
/**
* Internal copy directory method.
*
- * @param srcDir the validated source directory, not null
- * @param destDir the validated destination directory, not null
+ * @param srcDir the validated source directory, must not be <code>null</code>
+ * @param destDir the validated destination directory, must not be <code>null</code>
* @param preserveFileDate whether to preserve the file date
* @throws IOException if an error occurs
* @since Commons IO 1.1
@@ -829,9 +831,9 @@
* will be created if they don't already exist. <code>destination</code>
* will be overwritten if it already exists.
*
- * @param source the <code>URL</code> to copy bytes from, not null
+ * @param source the <code>URL</code> to copy bytes from, must not be <code>null</code>
* @param destination the non-directory <code>File</code> to write bytes to
- * (possibly overwriting), not null
+ * (possibly overwriting), must not be <code>null</code>
* @throws IOException if <code>source</code> URL cannot be opened
* @throws IOException if <code>destination</code> is a directory
* @throws IOException if <code>destination</code> cannot be written
@@ -916,10 +918,10 @@
* This method repeatedly tests {@link File#exists()} until it returns
* true up to the maximum time specified in seconds.
*
- * @param file the file to check, not null
+ * @param file the file to check, must not be <code>null</code>
* @param seconds the maximum time in seconds to wait
* @return true if file exists
- * @throws NullPointerException if the file is null
+ * @throws NullPointerException if the file is <code>null</code>
*/
public static boolean waitFor(File file, int seconds) {
int timeout = 0;
@@ -947,9 +949,9 @@
* Reads the contents of a file into a String.
* The file is always closed.
*
- * @param file the file to read, not null
- * @param encoding the encoding to use, null means platform default
- * @return the file contents, never null
+ * @param file the file to read, must not be <code>null</code>
+ * @param encoding the encoding to use, <code>null</code> means platform default
+ * @return the file contents, never <code>null</code>
* @throws IOException in case of an I/O error
* @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
*/
@@ -968,8 +970,8 @@
* Reads the contents of a file into a String using the default encoding for the VM.
* The file is always closed.
*
- * @param file the file to read, not null
- * @return the file contents, never null
+ * @param file the file to read, must not be <code>null</code>
+ * @return the file contents, never <code>null</code>
* @throws IOException in case of an I/O error
* @since Commons IO 1.3
*/
@@ -981,8 +983,8 @@
* Reads the contents of a file into a byte array.
* The file is always closed.
*
- * @param file the file to read, not null
- * @return the file contents, never null
+ * @param file the file to read, must not be <code>null</code>
+ * @return the file contents, never <code>null</code>
* @throws IOException in case of an I/O error
* @since Commons IO 1.1
*/
@@ -1000,9 +1002,9 @@
* Reads the contents of a file line by line to a List of Strings.
* The file is always closed.
*
- * @param file the file to read, not null
- * @param encoding the encoding to use, null means platform default
- * @return the list of Strings representing each line in the file, never null
+ * @param file the file to read, must not be <code>null</code>
+ * @param encoding the encoding to use, <code>null</code> means platform default
+ * @return the list of Strings representing each line in the file, never <code>null</code>
* @throws IOException in case of an I/O error
* @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
* @since Commons IO 1.1
@@ -1021,8 +1023,8 @@
* Reads the contents of a file line by line to a List of Strings using the default encoding for the VM.
* The file is always closed.
*
- * @param file the file to read, not null
- * @return the list of Strings representing each line in the file, never null
+ * @param file the file to read, must not be <code>null</code>
+ * @return the list of Strings representing each line in the file, never <code>null</code>
* @throws IOException in case of an I/O error
* @since Commons IO 1.3
*/
@@ -1055,9 +1057,9 @@
* If an exception occurs during the creation of the iterator, the
* underlying stream is closed.
*
- * @param file the file to read, not null
- * @param encoding the encoding to use, null means platform default
- * @return an Iterator of the lines in the file, never null
+ * @param file the file to open for input, must not be <code>null</code>
+ * @param encoding the encoding to use, <code>null</code> means platform default
+ * @return an Iterator of the lines in the file, never <code>null</code>
* @throws IOException in case of an I/O error (file closed)
* @since Commons IO 1.2
*/
@@ -1078,6 +1080,9 @@
/**
* Return an Iterator for the lines in a <code>File</code> using the default encoding for the VM.
*
+ * @param file the file to open for input, must not be <code>null</code>
+ * @return an Iterator of the lines in the file, never <code>null</code>
+ * @throws IOException in case of an I/O error (file closed)
* @since Commons IO 1.3
* @see #lineIterator(File, String)
*/
@@ -1094,7 +1099,7 @@
*
* @param file the file to write
* @param data the content to write to the file
- * @param encoding the encoding to use, null means platform default
+ * @param encoding the encoding to use, <code>null</code> means platform default
* @throws IOException in case of an I/O error
* @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
*/
@@ -1149,8 +1154,8 @@
* if they do not exist.
*
* @param file the file to write to
- * @param encoding the encoding to use, null means platform default
- * @param lines the lines to write, null entries produce blank lines
+ * @param encoding the encoding to use, <code>null</code> means platform default
+ * @param lines the lines to write, <code>null</code> entries produce blank lines
* @throws IOException in case of an I/O error
* @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
* @since Commons IO 1.1
@@ -1165,7 +1170,7 @@
* The default VM encoding and the default line ending will be used.
*
* @param file the file to write to
- * @param lines the lines to write, null entries produce blank lines
+ * @param lines the lines to write, <code>null</code> entries produce blank lines
* @throws IOException in case of an I/O error
* @since Commons IO 1.3
*/
@@ -1182,9 +1187,9 @@
* if they do not exist.
*
* @param file the file to write to
- * @param encoding the encoding to use, null means platform default
- * @param lines the lines to write, null entries produce blank lines
- * @param lineEnding the line separator to use, null is system default
+ * @param encoding the encoding to use, <code>null</code> means platform default
+ * @param lines the lines to write, <code>null</code> entries produce blank lines
+ * @param lineEnding the line separator to use, <code>null</code> is system default
* @throws IOException in case of an I/O error
* @throws java.io.UnsupportedEncodingException if the encoding is not supported by the VM
* @since Commons IO 1.1
@@ -1205,8 +1210,8 @@
* The default VM encoding and the specified line ending will be used.
*
* @param file the file to write to
- * @param lines the lines to write, null entries produce blank lines
- * @param lineEnding the line separator to use, null is system default
+ * @param lines the lines to write, <code>null</code> entries produce blank lines
+ * @param lineEnding the line separator to use, <code>null</code> is system default
* @throws IOException in case of an I/O error
* @since Commons IO 1.3
*/
@@ -1225,8 +1230,8 @@
* (java.io.File methods returns a boolean)</li>
* </ul>
*
- * @param file file or directory to delete, not null
- * @throws NullPointerException if the directory is null
+ * @param file file or directory to delete, must not be <code>null</code>
+ * @throws NullPointerException if the directory is <code>null</code>
* @throws IOException in case deletion is unsuccessful
*/
public static void forceDelete(File file) throws IOException {
@@ -1248,8 +1253,8 @@
* Schedule a file to be deleted when JVM exits.
* If file is directory delete it and all sub-directories.
*
- * @param file file or directory to delete, not null
- * @throws NullPointerException if the file is null
+ * @param file file or directory to delete, must not be <code>null</code>
+ * @throws NullPointerException if the file is <code>null</code>
* @throws IOException in case deletion is unsuccessful
*/
public static void forceDeleteOnExit(File file) throws IOException {
@@ -1263,8 +1268,8 @@
/**
* Recursively schedule directory for deletion on JVM exit.
*
- * @param directory directory to delete, not null
- * @throws NullPointerException if the directory is null
+ * @param directory directory to delete, must not be <code>null</code>
+ * @throws NullPointerException if the directory is <code>null</code>
* @throws IOException in case deletion is unsuccessful
*/
private static void deleteDirectoryOnExit(File directory) throws IOException {
@@ -1279,8 +1284,8 @@
/**
* Clean a directory without deleting it.
*
- * @param directory directory to clean, not null
- * @throws NullPointerException if the directory is null
+ * @param directory directory to clean, must not be <code>null</code>
+ * @throws NullPointerException if the directory is <code>null</code>
* @throws IOException in case cleaning is unsuccessful
*/
private static void cleanDirectoryOnExit(File directory) throws IOException {
@@ -1319,8 +1324,8 @@
* directories. If there already exists a file with specified name or
* the directory cannot be created then an exception is thrown.
*
- * @param directory directory to create, not null
- * @throws NullPointerException if the directory is null
+ * @param directory directory to create, must not be <code>null</code>
+ * @throws NullPointerException if the directory is <code>null</code>
* @throws IOException if the directory cannot be created
*/
public static void forceMkdir(File directory) throws IOException {
@@ -1346,9 +1351,9 @@
/**
* Recursively count size of a directory (sum of the length of all files).
*
- * @param directory directory to inspect, not null
+ * @param directory directory to inspect, must not be <code>null</code>
* @return size of directory in bytes, 0 if directory is security restricted
- * @throws NullPointerException if the directory is null
+ * @throws NullPointerException if the directory is <code>null</code>
*/
public static long sizeOfDirectory(File directory) {
if (!directory.exists()) {
@@ -1386,13 +1391,13 @@
* <code>File</code>.
*
* @param file the <code>File</code> of which the modification date must
- * be compared, not null
+ * be compared, must not be <code>null</code>
* @param reference the <code>File</code> of which the modification date
- * is used, not null
+ * is used, must not be <code>null</code>
* @return true if the <code>File</code> exists and has been modified more
* recently than the reference <code>File</code>
- * @throws IllegalArgumentException if the file is null
- * @throws IllegalArgumentException if the reference file is null or doesn't exist
+ * @throws IllegalArgumentException if the file is <code>null</code>
+ * @throws IllegalArgumentException if the reference file is <code>null</code> or doesn't exist
*/
public static boolean isFileNewer(File file, File reference) {
if (reference == null) {
@@ -1410,12 +1415,12 @@
* <code>Date</code>.
*
* @param file the <code>File</code> of which the modification date
- * must be compared, not null
- * @param date the date reference, not null
+ * must be compared, must not be <code>null</code>
+ * @param date the date reference, must not be <code>null</code>
* @return true if the <code>File</code> exists and has been modified
* after the given <code>Date</code>.
- * @throws IllegalArgumentException if the file is null
- * @throws IllegalArgumentException if the date is null
+ * @throws IllegalArgumentException if the file is <code>null</code>
+ * @throws IllegalArgumentException if the date is <code>null</code>
*/
public static boolean isFileNewer(File file, Date date) {
if (date == null) {
@@ -1429,12 +1434,12 @@
* time reference.
*
* @param file the <code>File</code> of which the modification date must
- * be compared, not null
+ * be compared, must not be <code>null</code>
* @param timeMillis the time reference measured in milliseconds since the
* epoch (00:00:00 GMT, January 1, 1970)
* @return true if the <code>File</code> exists and has been modified after
* the given time reference.
- * @throws IllegalArgumentException if the file is null
+ * @throws IllegalArgumentException if the file is <code>null</code>
*/
public static boolean isFileNewer(File file, long timeMillis) {
if (file == null) {
@@ -1453,13 +1458,13 @@
* <code>File</code>.
*
* @param file the <code>File</code> of which the modification date must
- * be compared, not null
+ * be compared, must not be <code>null</code>
* @param reference the <code>File</code> of which the modification date
- * is used, not null
+ * is used, must not be <code>null</code>
* @return true if the <code>File</code> exists and has been modified before
* the reference <code>File</code>
- * @throws IllegalArgumentException if the file is null
- * @throws IllegalArgumentException if the reference file is null or doesn't exist
+ * @throws IllegalArgumentException if the file is <code>null</code>
+ * @throws IllegalArgumentException if the reference file is <code>null</code> or doesn't exist
*/
public static boolean isFileOlder(File file, File reference) {
if (reference == null) {
@@ -1477,12 +1482,12 @@
* <code>Date</code>.
*
* @param file the <code>File</code> of which the modification date
- * must be compared, not null
- * @param date the date reference, not null
+ * must be compared, must not be <code>null</code>
+ * @param date the date reference, must not be <code>null</code>
* @return true if the <code>File</code> exists and has been modified
* before the given <code>Date</code>.
- * @throws IllegalArgumentException if the file is null
- * @throws IllegalArgumentException if the date is null
+ * @throws IllegalArgumentException if the file is <code>null</code>
+ * @throws IllegalArgumentException if the date is <code>null</code>
*/
public static boolean isFileOlder(File file, Date date) {
if (date == null) {
@@ -1496,12 +1501,12 @@
* time reference.
*
* @param file the <code>File</code> of which the modification date must
- * be compared, not null
+ * be compared, must not be <code>null</code>
* @param timeMillis the time reference measured in milliseconds since the
* epoch (00:00:00 GMT, January 1, 1970)
* @return true if the <code>File</code> exists and has been modified before
* the given time reference.
- * @throws IllegalArgumentException if the file is null
+ * @throws IllegalArgumentException if the file is <code>null</code>
*/
public static boolean isFileOlder(File file, long timeMillis) {
if (file == null) {
@@ -1518,9 +1523,9 @@
* Computes the checksum of a file using the CRC32 checksum routine.
* The value of the checksum is returned.
*
- * @param file the file to checksum, not null
+ * @param file the file to checksum, must not be <code>null</code>
* @return the checksum value
- * @throws NullPointerException if the file or checksum is null
+ * @throws NullPointerException if the file or checksum is <code>null</code>
* @throws IllegalArgumentException if the file is a directory
* @throws IOException if an IO error occurs reading the file
* @since Commons IO 1.3
@@ -1540,10 +1545,10 @@
* long csum = FileUtils.checksum(file, new CRC32()).getValue();
* </pre>
*
- * @param file the file to checksum, not null
- * @param checksum the checksum object to be used, not null
+ * @param file the file to checksum, must not be <code>null</code>
+ * @param checksum the checksum object to be used, must not be <code>null</code>
* @return the checksum specified, updated with the content of the file
- * @throws NullPointerException if the file or checksum is null
+ * @throws NullPointerException if the file or checksum is <code>null</code>
* @throws IllegalArgumentException if the file is a directory
* @throws IOException if an IO error occurs reading the file
* @since Commons IO 1.3
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
RE: [io] svn commit: r491668 - /jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
Posted by Gary Gregory <gg...@seagullsoftware.com>.
Hi All:
Interesting and I do see your POV. IMO, it also depends on what tools
you use do to your work. I use the Eclipse Javadoc view which presents
the Javadoc comment in a formatted HTML view. I never bother to use the
source of Javadocs to understand what the comments "say" as there
usually is too much meta information, {@links} and {@whatnots}, to
really make reading easy.
I guess it comes down to how you want to present each [project] to the
outside world. Since I find the Sun JRE Javadoc usually pretty poor, in
general, I do like to make my Java comments more technically detailed
and prettier.
Feel free to replace all <code>null</code> with null ;)
Thank you,
Gary
> -----Original Message-----
> From: Stephen Colebourne [mailto:scolebourne@btopenworld.com]
> Sent: Monday, January 01, 2007 5:36 PM
> To: Jakarta Commons Developers List
> Subject: Re: [io] svn commit: r491668 -
>
/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtil
s.
> java
>
> I'll be honest and say I dislike the convention of using <code> for
> null, as as such I'm not greatly enthused by this change. I'd prefer
if
> no more files were changed.
>
> This comes down to my basic tenet that javadoc is for developers to
> read, and it is *frequently* read as source code, not as an HTML page.
> Adding the <code> makes its *much* more difficult for someone to read
> the text. And its the text that matters.
>
> Just read the two lines below and decide which is easier to read and
> extract meaning from.
>
> In addition, since every Java programmer knows that null is a reserved
> word, I really don't see what is gained by highlighting it.
>
> Stephen
>
>
> ggregory@apache.org wrote:
> > Author: ggregory
> > Date: Mon Jan 1 14:45:49 2007
> > New Revision: 491668
> >
> > URL: http://svn.apache.org/viewvc?view=rev&rev=491668
> > Log:
> > Add missing Javadoc tags. Use "null" is code format
(<code>null</code>)
> >
>
> > - * @param file the file to open for input, not null
> > + * @param file the file to open for input, must not be
<code>null</code>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] svn commit: r491668 - /jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
Posted by Stephen Colebourne <sc...@btopenworld.com>.
I'll be honest and say I dislike the convention of using <code> for
null, as as such I'm not greatly enthused by this change. I'd prefer if
no more files were changed.
This comes down to my basic tenet that javadoc is for developers to
read, and it is *frequently* read as source code, not as an HTML page.
Adding the <code> makes its *much* more difficult for someone to read
the text. And its the text that matters.
Just read the two lines below and decide which is easier to read and
extract meaning from.
In addition, since every Java programmer knows that null is a reserved
word, I really don't see what is gained by highlighting it.
Stephen
ggregory@apache.org wrote:
> Author: ggregory
> Date: Mon Jan 1 14:45:49 2007
> New Revision: 491668
>
> URL: http://svn.apache.org/viewvc?view=rev&rev=491668
> Log:
> Add missing Javadoc tags. Use "null" is code format (<code>null</code>)
>
> - * @param file the file to open for input, not null
> + * @param file the file to open for input, must not be <code>null</code>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org