From 9675a4bb71da0f01e58b0ccd136e2badd88caa01 Mon Sep 17 00:00:00 2001
From: Dan Gohman <dev@sunfishcode.online>
Date: Wed, 13 Sep 2023 12:05:57 -0700
Subject: [PATCH] Document that filesystem timestamps can be 0. (#124)

* Document that filesystem timestamps can be 0.

A value of 0 in a timestamp indicates the time is unknown. This
ports #531 from Preview 1 to Preview 2.

* Fix a copy+pasto.

* Regenerate example-world.md.

* Switch to `option` instead of special-casing 0.
---
 example-world.md | 14 ++++++++++----
 wit/types.wit    | 17 +++++++++++++----
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/example-world.md b/example-world.md
index 7805cf8..533ff39 100644
--- a/example-world.md
+++ b/example-world.md
@@ -754,16 +754,22 @@ with the filesystem.
 length in bytes of the pathname contained in the symbolic link.
 </li>
 <li>
-<p><a name="descriptor_stat.data_access_timestamp"><code>data-access-timestamp</code></a>: <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></p>
+<p><a name="descriptor_stat.data_access_timestamp"><code>data-access-timestamp</code></a>: option&lt;<a href="#datetime"><a href="#datetime"><code>datetime</code></a></a>&gt;</p>
 <p>Last data access timestamp.
+<p>If the <code>option</code> is none, the platform doesn't maintain an access
+timestamp for this file.</p>
 </li>
 <li>
-<p><a name="descriptor_stat.data_modification_timestamp"><code>data-modification-timestamp</code></a>: <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></p>
+<p><a name="descriptor_stat.data_modification_timestamp"><code>data-modification-timestamp</code></a>: option&lt;<a href="#datetime"><a href="#datetime"><code>datetime</code></a></a>&gt;</p>
 <p>Last data modification timestamp.
+<p>If the <code>option</code> is none, the platform doesn't maintain a
+modification timestamp for this file.</p>
 </li>
 <li>
-<p><a name="descriptor_stat.status_change_timestamp"><code>status-change-timestamp</code></a>: <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></p>
-<p>Last file status change timestamp.
+<p><a name="descriptor_stat.status_change_timestamp"><code>status-change-timestamp</code></a>: option&lt;<a href="#datetime"><a href="#datetime"><code>datetime</code></a></a>&gt;</p>
+<p>Last file status-change timestamp.
+<p>If the <code>option</code> is none, the platform doesn't maintain a
+status-change timestamp for this file.</p>
 </li>
 </ul>
 <h4><a name="advice"><code>enum advice</code></a></h4>
diff --git a/wit/types.wit b/wit/types.wit
index 9b1412d..c7e817d 100644
--- a/wit/types.wit
+++ b/wit/types.wit
@@ -107,11 +107,20 @@ interface types {
         /// length in bytes of the pathname contained in the symbolic link.
         size: filesize,
         /// Last data access timestamp.
-        data-access-timestamp: datetime,
+        ///
+        /// If the `option` is none, the platform doesn't maintain an access
+        /// timestamp for this file.
+        data-access-timestamp: option<datetime>,
         /// Last data modification timestamp.
-        data-modification-timestamp: datetime,
-        /// Last file status change timestamp.
-        status-change-timestamp: datetime,
+        ///
+        /// If the `option` is none, the platform doesn't maintain a
+        /// modification timestamp for this file.
+        data-modification-timestamp: option<datetime>,
+        /// Last file status-change timestamp.
+        ///
+        /// If the `option` is none, the platform doesn't maintain a
+        /// status-change timestamp for this file.
+        status-change-timestamp: option<datetime>,
     }
 
     /// Flags determining the method of how paths are resolved.