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

Brian Burkhalter brian.burkhalter at oracle.com
Wed May 17 20:28:02 UTC 2017


Hi Stuart,

Thanks for the careful reading and comments.

On May 17, 2017, at 1:15 PM, Stuart Marks <stuart.marks at oracle.com> wrote:

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

Good points.

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

This wording "the unit of time of the return value is a millisecond” sounds weird. I would have written "the unit of time of the return value is milliseconds.”

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

How about then (ignore formatting)?

    * @apiNote
    * While the unit of time of the return value is milliseconds,
    * the granularity of the value depends on the underlying
    * file system and may be larger.  For example, some
    * file systems use time stamps in units of seconds.

Thanks,

Brian


More information about the core-libs-dev mailing list