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

[Brian Burkhalter]

On May 25, 2017, at 3:37 PM, Stuart Marks <stuart.marks at oracle.com> wrote:

> The test in the @return paragraph is fine.

I think you intended “text.”

> The new text at the end of the @apiNote is ok...
> 
> […]
> 
> The "granularity" sentences currently in the @apiNote can remain, but probably in a separate paragraph in the @apiNote.

I agree with the foregoing. I’ll take another pass over it tomorrow.

> 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.

I was only looking at this one particular thing and not reviewing the verbiage of the entire class. I would prefer to note the problems and file a separate issue to deal with them.

Thanks,

Brian