Hi Stuart,
Thanks for the careful reading and comments.
On May 17, 2017, at 1:15 PM, Stuart Marks <stuart.ma...@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
