JDK 9 doc-api-only RFR of 7086489: File.lastModified should accuracy as well as resolution

[Stuart Marks]

This is for JDK 9, right, so we want only non-normative doc changes?

I'd think this should be an @apiNote instead of @implSpec. The @apiNote 
clarifies but doesn't change the semantics, whereas @implSpec can impose 
requirements on the implementation and is thus normative.

The intent of the wording is correct, but I also think it's potentially 
confusing, particularly regarding "truncation." If the time resolution (or 
"granularity") in a particular file system is one second, the value returned is 
converted from seconds to milliseconds and no truncation occurs. The "last three 
digits...zero" assumes the value is expressed in decimal, which isn't incorrect, 
but it seems to require more explanation to make sense. I'd leave it out.

For APIs with similar issues, see System.currentTimeMillis() and 
System.nanoTime(). In particular, currentTimeMillis() says:

      * Returns the current time in milliseconds.  Note that
      * while the unit of time of the return value is a millisecond,
      * the granularity of the value depends on the underlying
      * operating system and may be larger.  For example, many
      * operating systems measure time in units of tens of
      * milliseconds.

I'm not sure "granularity" is the best term, but it seems OK. Maybe the best 
thing to do would be to use this wording and adjust "operating system" to "file 
system".

s'marks

On 5/17/17 12:16 PM, Brian Burkhalter wrote:
> Please review at your convenience.
>
> Issue:	https://bugs.openjdk.java.net/browse/JDK-7086489
> Patch:	[1]
>
> Thanks,
>
> Brian
>
> [1] Hg mq diff
>
> --- a/src/java.base/share/classes/java/io/File.java
> +++ b/src/java.base/share/classes/java/io/File.java
> @@ -923,6 +923,12 @@
>       * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
>       * Files.readAttributes} method may be used.
>       *
> +     * @implSpec While the unit of the returned value is milliseconds, this
> +     * does not imply that its accuracy is to the millisecond as some platforms
> +     * may truncate the last-modified time to a less accurate value. For
> +     * example if the value were truncated to seconds, then the last three
> +     * digits of the returned value would all be zero.
> +     *
>       * @return  A <code>long</code> value representing the time the file was
>       *          last modified, measured in milliseconds since the epoch
>       *          (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
>