On 5/25/17 8:32 AM, Brian Burkhalter wrote:
This is a continuation / merge of two previous RFRs:
6791812:
http://mail.openjdk.java.net/pipermail/core-libs-dev/2017-May/047787.html
8180767:
http://mail.openjdk.java.net/pipermail/core-libs-dev/2017-May/047809.html
An updated patch which folds the second change into the first is here:
http://cr.openjdk.java.net/~bpb/6791812/webrev.00/
If this is approved I will update the corresponding CCC request and after
eventually pushing the patch will resolve 8180767 as a duplicate.
The test in the @return paragraph is fine.
The new text at the end of the @apiNote is ok...
931 * Distinguishing an I/O exception from a zero return value may
932 * also be accomplished by using the
933 * {@link java.nio.file.Files#getLastModifiedTime(Path,LinkOption[])
934 * Files.getLastModifiedTime} method.
but it's redundant with the text in the paragraph that precedes the @apiNote.
This covers the same issue, but it suggests a different alternative:
919 * <p> Where it is required to distinguish an I/O exception from the
case
920 * where {@code 0L} is returned, or where several attributes of the
921 * same file are required at the same time, or where the time of last
922 * access or the creation time are required, then the {@link
923 * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
924 * Files.readAttributes} method may be used.
None of this is wrong, but it's weird to have two paragraphs that address the
same issue in different ways, one within an @apiNote and the other not.
I'd suggest merging all of this into the @apiNote. Some rewording is probably
necessary. There are too many different circumstances and alternatives to cover
in a single sentence. But maybe this is trying to cover too much. It might
simplify things if it simply mentions the problem and points people elsewhere:
@apiNote
This method returns {@code 0L} in cases where an I/O exception occurs or
where the actual modification time is {@code 0L}. To distinguish these
cases, consider calling {@link
java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
Files.readAttributes} or {@link
java.nio.file.Files#getLastModifiedTime(Path,LinkOption[])
Files.readAttributes} instead.
The "granularity" sentences currently in the @apiNote can remain, but probably
in a separate paragraph in the @apiNote.
**
The problem with fixing up javadoc in one place is that it becomes inconsistent
with other places.
For example, File.length() has similar "Where it is required to distinguish..."
wording. This should also be made into an @apiNote and also reworded to be in
alignment with whatever text is used in File.lastModified().
Also, File.createNewFile(), File.delete(), and File.deleteOnExit() have words to
the effect of "Note: ..." or "Note that..." which indicate API notes, but which
aren't tagged with @apiNote. The @apiNote tag should probably be added to those
as well.
These can be handled separately if you like. Unless you're really ambitious, in
which case you can fix them all in a single changeset. Up to you.
s'marks
