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
