@@ -23,3 +29,4 @@
 	NotFound,
 
 	// Category: bad request
+	/// The request used an invalid path

@@ -52,6 +65,7 @@ impl From<roxmltree::Error> for Error {
 }
 
 impl Error {
+	/// Convert an error into an Http status code

@@ -3,2 +5,3 @@
 
-pub mod error;
+mod error;
+pub use error::Error;

@@ -1,4 +1,6 @@
+#![deny(missing_crate_level_docs, missing_docs)]
 #![recursion_limit = "1024"]
+//! Garage CLI, used to interact with a running Garage instance, and to launch a Garage

@@ -142,3 +157,4 @@
 	}
 
+	/// Write a block to disk
 	pub async fn write_block(&self, hash: &Hash, data: &[u8]) -> Result<Message, Error> {

@@ -230,2 +250,4 @@
 	}
 
+	/// Decrement the number of time a block is used
+	// when counter reach 0, it seems not put to resync which I assume put it to gc?

@@ -14,3 +15,4 @@
 	pub block: Hash,
 
 	// Sort key
+	// why a version on a hashed (probably immutable) piece of data?

@@ -17,3 +19,4 @@
 	pub version: UUID,
 
 	// Keep track of deleted status
+	/// Is that block deleted

@@ -60,15 +67,21 @@ impl BucketParams {
 }
 
 impl Bucket {
+	/// Create a new bucket

@@ -67,2 +75,4 @@
 		}
 	}
+
+	/// Query if bucket is deleted

@@ -102,1 +115,4 @@
 
+	fn updated(&self, _old: Option<Self::E>, _new: Option<Self::E>) {
+		// nothing to do when updated
+	}

@@ -20,3 +21,2 @@
-	// Authorized keys
+	/// Buckets in which the key is authorized. Empty if `Key` is deleted
 	pub authorized_buckets: crdt::LWWMap<String, PermissionSet>,
-	// CRDT interaction: deleted implies authorized_buckets is empty

@@ -6,3 +7,3 @@
 #[derive(PartialEq, Clone, Debug, Serialize, Deserialize)]
 pub struct Key {
-	// Primary key
+	/// The id of the key (immutable)

@@ -17,3 +18,3 @@
 	pub bucket: String,
 
-	// Sort key
+	/// The key at which the object is stored in its bucket

@@ -20,3 +21,3 @@
 	pub key: String,
 
-	// Data
+	/// The list of known versions of the object

@@ -50,2 +53,4 @@
 		}
 	}
+
+	/// Get a list of all versions known for `Object`

@@ -67,2 +77,4 @@
 	Uploading(ObjectVersionHeaders),
+	/// The version is fully received
 	Complete(ObjectVersionData),
+	/// The version was never fully received

@@ -93,2 +105,4 @@
+/// Data about an object version
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Serialize, Deserialize)]
 pub enum ObjectVersionData {
+	/// The version is deleted

@@ -131,2 +159,4 @@
 		}
 	}
+
+	/// Is the object version available (received and not deleted)

@@ -13,3 +14,3 @@
 #[derive(PartialEq, Clone, Debug, Serialize, Deserialize)]
 pub struct Version {
-	// Primary key
+	/// UUID of the version

@@ -43,7 +49,9 @@ impl Version {
 
 #[derive(PartialEq, Eq, Clone, Copy, Debug, Serialize, Deserialize)]
 pub struct VersionBlockKey {
+	/// Number of the part, starting at 1

@@ -1,3 +1,4 @@
+/// Module containing structs related to membership management

@@ -78,28 +95,39 @@ pub struct System {
 	rpc_client: Arc<RpcClient<Message>>,
 
 	pub(crate) status: watch::Receiver<Arc<Status>>,
+	/// The ring, viewed by this node

@@ -88,2 +108,4 @@
 #[derive(Debug, Clone)]
 pub struct Status {
+	/// Mapping of each node id to its known status
+	// considering its sorted regularly, maybe it should be a btreeset?

@@ -90,1 +110,4 @@
+	/// Mapping of each node id to its known status
+	// considering its sorted regularly, maybe it should be a btreeset?
 	pub nodes: HashMap<UUID, Arc<StatusEntry>>,
+	/// Hash of this entry

@@ -96,2 +121,4 @@
 	pub addr: SocketAddr,
+	/// Last time this node was seen
 	pub last_seen: u64,
+	/// Number of consecutive pings sent without reply to this node

@@ -341,3 +373,3 @@
 					addr,
 					sys.rpc_client
-						.by_addr()
+						.get_addr()

@@ -1,3 +1,4 @@
+//! Module containing types related to computing nodes which should receive a copy of data blocks

@@ -23,2 +27,4 @@
+/// The maximum number of time an object might get replicated
 pub const MAX_REPLICATION: usize = 3;
 
+/// The versionned configurations of all nodes known in the network

@@ -180,3 +197,4 @@
 		top >> (16 - PARTITION_BITS)
 	}
 
+	/// Get the list of partitions and

@@ -193,6 +211,7 @@ impl Ring {
 		ret
 	}
 
+	/// Walk the ring to find the n servers in which data should be replicated

@@ -201,12 +220,15 @@ impl Ring {
 
 		let top = u16::from_be_bytes(from.as_slice()[0..2].try_into().unwrap());
 		let partition_idx = (top >> (16 - PARTITION_BITS)) as usize;
+		// TODO why computing two time in the same way and asserting?

@@ -45,3 +52,4 @@
 		self.rs_timeout = timeout;
 		self
 	}
+	/// Set if requests can be dropped after quorum has been reached

@@ -92,2 +105,3 @@
 
-	pub fn by_addr(&self) -> &RpcAddrClient<M> {
+	/// Get the server address this client connect to
+	pub fn get_addr(&self) -> &RpcAddrClient<M> {

@@ -150,2 +167,4 @@
 	}
 
+	/// Make a RPC call to multiple servers, returning either a Vec of responses, or an error if
+	/// strategy could not be respected due to to many errors

@@ -208,6 +227,7 @@ impl<M: RpcMessage + 'static> RpcClient<M> {
 	}
 }
 
+/// Endpoint to which send RPC

@@ -14,2 +16,4 @@
 	fn write_nodes(&self, hash: &Hash) -> Vec<UUID>;
+	/// Responses needed to consider a write succesfull
 	fn write_quorum(&self) -> usize;
+	// this feels like its write_nodes().len() - write_quorum()

@@ -4,7 +4,9 @@ use garage_util::data::*;
 
 use crate::crdt::CRDT;
 
+/// Trait for partitionnable data

@@ -20,7 +22,9 @@ impl PartitionKey for Hash {
 	}
 }
 
+/// Trait for sortable data

@@ -64,3 +77,3 @@
 	// due to CRDT logic. Typically errors in propagation of info should be logged
 	// to stderr.
-	fn updated(&self, _old: Option<Self::E>, _new: Option<Self::E>) {}
+	fn updated(&self, old: Option<Self::E>, new: Option<Self::E>);

@@ -16,3 +20,3 @@
 	NotFound,
 
-	// Category: bad request
+	/// The client requested a malformed path

@@ -387,2 +418,4 @@
 			} else if let Some(id) = id_option {
 				if let Some(st) = status.nodes.get_mut(id) {
+					// TODO this might double-increment the value as the counter is already
+					// incremented for any kind of failure in rpc_client