Make explicit the precondition that versions must be <= latest version

include/ConflictSet.h

@@ -54,8 +54,9 @@ struct __attribute__((__visibility__("default"))) ConflictSet {
     /** `end` having length 0 denotes that this range is the single key {begin}.
      * Otherwise this denotes the range [begin, end), and begin must be < end */
     Key end;
-    /** `readVersion` older than the the oldestVersion or the version of the
-     * latest call to `addWrites` minus two billion will result in `TooOld` */
+    /** `readVersion` older than the oldestVersion or the version of the
+     * latest call to `addWrites` minus two billion will result in `TooOld`.
+     * Must be <= the version of the latest call to `addWrites` */
     int64_t readVersion;
   };
 
@@ -72,11 +73,13 @@ struct __attribute__((__visibility__("default"))) ConflictSet {
 
   /** Reads intersecting writes where readVersion < `writeVersion` will result
    * in `Conflict` (or `TooOld`, eventually).  `writeVersion` must be greater
-   * than or equal to all previous write versions. */
+   * than or equal to all previous write versions. Call `addWrites` with `count`
+   * zero to only advance the version. */
   void addWrites(const WriteRange *writes, int count, int64_t writeVersion);
 
-  /** Reads where readVersion < oldestVersion will result in `TooOld`. Must be
-   * greater than or equal to all previous oldest versions. */
+  /** Reads where readVersion < `oldestVersion` will result in `TooOld`. Must be
+   * greater than or equal to all previous oldest versions. Must be <= the
+   * version of the latest call to `addWrites` */
   void setOldestVersion(int64_t oldestVersion);
 
   /** Reads where readVersion < oldestVersion will result in `TooOld`. There are
@@ -170,8 +173,9 @@ typedef struct {
   /** `end` having length 0 denotes that this range is the single key {begin}.
    * Otherwise this denotes the range [begin, end), and begin must be < end */
   ConflictSet_Key end;
-  /** `readVersion` older than the the oldestVersion or the version of the
-   * latest call to `addWrites` minus two billion will result in `TooOld` */
+  /** `readVersion` older than the oldestVersion or the version of the
+   * latest call to `addWrites` minus two billion will result in `TooOld`.
+   * Must be <= the version of the latest call to `addWrites` */
   int64_t readVersion;
 } ConflictSet_ReadRange;
 
@@ -188,15 +192,17 @@ void ConflictSet_check(const ConflictSet *cs,
                        const ConflictSet_ReadRange *reads,
                        ConflictSet_Result *results, int count);
 
-/** Reads intersecting writes where readVersion < `writeVersion` will result in
- * `Conflict` (or `TooOld`, eventually).  `writeVersion` must be greater than or
- * equal to all previous write versions.  */
+/** Reads intersecting writes where readVersion < `writeVersion` will result
+ * in `Conflict` (or `TooOld`, eventually).  `writeVersion` must be greater
+ * than or equal to all previous write versions. Call `addWrites` with `count`
+ * zero to only advance the version. */
 void ConflictSet_addWrites(ConflictSet *cs,
                            const ConflictSet_WriteRange *writes, int count,
                            int64_t writeVersion);
 
-/** Reads where readVersion < oldestVersion will result in `TooOld`. Must be
- * greater than or equal to all previous oldest versions. */
+/** Reads where readVersion < `oldestVersion` will result in `TooOld`. Must be
+ * greater than or equal to all previous oldest versions. Must be <= the
+ * version of the latest call to `addWrites` */
 void ConflictSet_setOldestVersion(ConflictSet *cs, int64_t oldestVersion);
 
 /** Reads where readVersion < oldestVersion will result in `TooOld`. There are