CRDT doc

src/model/bucket_table.rs

@@ -8,6 +8,9 @@ use garage_util::error::Error;
 
 use crate::key_table::PermissionSet;
 
+// We import the same file but in its version 0.1.0.
+// We can then access v0.1.0 data structures.
+// We use them to perform migrations.
 use model010::bucket_table as prev;
 
 #[derive(PartialEq, Clone, Debug, Serialize, Deserialize)]

src/table/crdt.rs

@@ -2,7 +2,26 @@ use serde::{Deserialize, Serialize};
 
 use garage_util::data::*;
 
+/// Conflict-free replicated data type (CRDT)
+///
+/// CRDT are a type of data structures that do not require coordination.
+/// In other words, we can edit them in parallel, we will always
+/// find a way to merge it.
+///
+/// A general example is a counter. Its initial value is 0.
+/// Alice and Bob get a copy of the counter.
+/// Alice does +1 on her copy, she reads 1.
+/// Bob does +3 on his copy, he reads 3.
+/// Now, it is easy to merge their counters, order does not count:
+/// we always get 4.
+///
+/// Learn more about CRDT [on Wikipedia](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type)
 pub trait CRDT {
+	/// Merge the two datastructures according to the CRDT rules
+	///
+	/// # Arguments
+	///
+	/// * `other` - the other copy of the CRDT
 	fn merge(&mut self, other: &Self);
 }
 
@@ -19,6 +38,9 @@ where
 
 // ---- LWW Register ----
 
+/// Last Write Win (LWW)
+///
+/// LWW is a very simple
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct LWW<T> {
 	ts: u64,
@@ -64,8 +86,9 @@ where
 	}
 }
 
-// ---- Boolean (true as absorbing state) ----
-
+/// Boolean
+///
+/// with True as absorbing state
 #[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
 pub struct Bool(bool);
 
@@ -87,8 +110,9 @@ impl CRDT for Bool {
 	}
 }
 
-// ---- LWW Map ----
-
+/// Last Write Win Map
+///
+///
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct LWWMap<K, V> {
 	vals: Vec<(K, u64, V)>,