From 393168ff53eb1d9a985b0b53d329a4c5b6baf1a8 Mon Sep 17 00:00:00 2001
From: Andrew Noyes <andrew@weaselab.dev>
Date: Mon, 6 May 2024 10:10:18 -0700
Subject: [PATCH] Clarify result of querying for key intersecting mutation

---
 include/VersionedMap.h | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/include/VersionedMap.h b/include/VersionedMap.h
index 1d119e7..5e9ddf9 100644
--- a/include/VersionedMap.h
+++ b/include/VersionedMap.h
@@ -121,9 +121,9 @@ struct VersionedMap {
     /** 0 if this iterator's param1 is equal to the queried key, < 0 if this
      * iterator's param1 is less than the queried key, and > 0 if this
      * iterator's param1 is greater than the queried key. Iterating forward is
-     * treated as a query for the first param1 greater than this iterator's key,
-     * so will always result in a `cmp` > 0, and the converse for iterating
-     * backward (`cmp` < 0). */
+     * treated as a query for the first mutation greater than this iterator's
+     * mutation, so will always result in a `cmp` > 0, and the converse for
+     * iterating backward (`cmp` < 0). */
     int cmp() const;
 
     /** @private */
@@ -133,12 +133,15 @@ struct VersionedMap {
     Impl *impl = nullptr;
   };
 
-  /** Perform `count` "first greater than or equal to" queries. The result of
-   * querying `key[i]` at `version[i]` is `iterator[i]`. `version[i]` must be >=
-   * `getOldestVersion()` and <= `getVersion()`. Thread-safe as long as a
-   * version is not concurrently invalidated by `setOldestVersion`. There's a
-   * performance benefit if you pass iterator[i] previously obtained at
-   * version[i]. */
+  /** Perform `count` "first greater than or equal to" queries. If there's a
+   * mutation intersecting `key[i]` at `version[i]` then `iterator[i]` will
+   * point to that mutation. Otherwise it points to the first mutation greater
+   * or `end()` if none exists.  `version[i]` must be >= `getOldestVersion()`
+   * and <= `getVersion()`.
+   *
+   * Thread-safe as long as a version is not concurrently invalidated by
+   * `setOldestVersion`. There's a performance benefit if you pass iterator[i]
+   * previously obtained at version[i]. */
   void firstGeq(const Key *key, const int64_t *version, Iterator *iterator,
                 int count) const;