[REVISED] JDK 9 doc-api-only RFR of 6791812: (file spec) Incompatible File.lastModified() and setLastModified() for negative time

[Stuart Marks]

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