From 451ac5b2b618a3a42ee470101b87b83c76a7fb4b Mon Sep 17 00:00:00 2001
From: Andrew Noyes <andrew@weaselab.dev>
Date: Thu, 7 Mar 2024 16:17:17 -0800
Subject: [PATCH] Improve ConflictSet.h readability

---
 include/ConflictSet.h | 36 ++++++++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 10 deletions(-)

diff --git a/include/ConflictSet.h b/include/ConflictSet.h
index 9f57635..2f24f55 100644
--- a/include/ConflictSet.h
+++ b/include/ConflictSet.h
@@ -31,12 +31,15 @@ struct __attribute__((__visibility__("default"))) ConflictSet {
        `setOldestVersion` */
     TooOld
   };
+
   /** Bytes ordered lexicographically */
   struct Key {
     const uint8_t *p;
     int len;
   };
-  /** Denotes a set of keys to be checked for conflicts */
+
+  /** Denotes a set of keys to be checked for conflicting writes since
+   * `readVersion` */
   struct ReadRange {
     Key begin;
     /** `end` having length 0 denotes that this range is the single key {begin}.
@@ -44,6 +47,7 @@ struct __attribute__((__visibility__("default"))) ConflictSet {
     Key end;
     int64_t readVersion;
   };
+
   /** Denotes a set of keys to be written at `writeVersion` */
   struct WriteRange {
     Key begin;
@@ -51,21 +55,25 @@ struct __attribute__((__visibility__("default"))) ConflictSet {
      * Otherwise this denotes the range [begin, end) */
     Key end;
   };
-  /** The result of checking reads[i] is written in results[i]. */
+
+  /** The result of checking reads[i] is written in results[i] */
   void check(const ReadRange *reads, Result *results, int count) const;
+
   /** `writes` must be sorted ascending, and must not have adjacent or
    * overlapping ranges. Reads intersecting writes where readVersion <
    * `writeVersion` will result in `Conflict` (or `TooOld`, eventually).
-   * `writeVersion must be greater than all write versions in all previous
+   * `writeVersion` must be greater than every write version in all previous
    * calls to `addWrites` */
   void addWrites(const WriteRange *writes, int count, int64_t writeVersion);
+
   /** Reads where readVersion < oldestVersion will result in `TooOld`. Must be
-   * greater than any previous oldestVersion. */
+   * greater than any previous oldestVersion */
   void setOldestVersion(int64_t oldestVersion);
 
   /** Reads where readVersion < oldestVersion will result in `TooOld`. There are
-   * no writes initially. */
+   * no writes initially */
   explicit ConflictSet(int64_t oldestVersion);
+
   ~ConflictSet();
 
 #if __cplusplus > 199711L
@@ -96,12 +104,15 @@ typedef enum {
      `setOldestVersion` */
   ConflictSet_TooOld
 } ConflictSet_Result;
+
 /** Bytes ordered lexicographically */
 typedef struct {
   const uint8_t *p;
   int len;
 } ConflictSet_Key;
-/** Denotes a set of keys to be checked for conflicts */
+
+/** Denotes a set of keys to be checked for conflicting writes since
+ * `readVersion` */
 typedef struct {
   ConflictSet_Key begin;
   /** `end` having length 0 denotes that this range is the single key {begin}.
@@ -109,6 +120,7 @@ typedef struct {
   ConflictSet_Key end;
   int64_t readVersion;
 } ConflictSet_ReadRange;
+
 /** Denotes a set of keys to be written at `writeVersion` */
 typedef struct {
   ConflictSet_Key begin;
@@ -117,23 +129,27 @@ typedef struct {
   ConflictSet_Key end;
 } ConflictSet_WriteRange;
 
-/** The result of checking reads[i] is written in results[i]. */
+/** The result of checking reads[i] is written in results[i] */
 void ConflictSet_check(ConflictSet *cs, const ConflictSet_ReadRange *reads,
                        ConflictSet_Result *results, int count);
+
 /** `writes` must be sorted ascending, and must not have adjacent or
  * overlapping ranges. Reads intersecting writes where readVersion <
  * `writeVersion` will result in `Conflict` (or `TooOld`, eventually).
- * `writeVersion must be greater than all write versions in all previous
+ * `writeVersion` must be greater than all write versions in all previous
  * calls to `addWrites` */
 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 any previous oldestVersion. */
+ * greater than any previous oldestVersion */
 void ConflictSet_setOldestVersion(ConflictSet *cs, int64_t oldestVersion);
+
 /** Reads where readVersion < oldestVersion will result in `TooOld`. There are
- * no writes initially. */
+ * no writes initially */
 ConflictSet *ConflictSet_create(int64_t oldestVersion);
+
 void ConflictSet_destroy(ConflictSet *cs);
 
 #endif