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