From 09abd09ab85189b15c3296407a5a8a803e93ebd0 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Wed, 16 Oct 2019 18:13:40 -0400
Subject: [PATCH] add docs for std.fs.File.updateTimes

---
 lib/std/fs/file.zig | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/lib/std/fs/file.zig b/lib/std/fs/file.zig
index 53ba3e8d15..32c221d063 100644
--- a/lib/std/fs/file.zig
+++ b/lib/std/fs/file.zig
@@ -269,9 +269,17 @@ pub const File = struct {
 
     pub const UpdateTimesError = os.FutimensError || windows.SetFileTimeError;
 
-    /// `atime`: access timestamp in nanoseconds
-    /// `mtime`: last modification timestamp in nanoseconds
-    pub fn updateTimes(self: File, atime: i64, mtime: i64) UpdateTimesError!void {
+    /// The underlying file system may have a different granularity than nanoseconds,
+    /// and therefore this function cannot guarantee any precision will be stored.
+    /// Further, the maximum value is limited by the system ABI. When a value is provided
+    /// that exceeds this range, the value is clamped to the maximum.
+    pub fn updateTimes(
+        self: File,
+        /// access timestamp in nanoseconds
+        atime: i64,
+        /// last modification timestamp in nanoseconds
+        mtime: i64,
+    ) UpdateTimesError!void {
         if (windows.is_the_target) {
             const atime_ft = windows.nanoSecondsToFileTime(atime);
             const mtime_ft = windows.nanoSecondsToFileTime(mtime);