From 41b105aac8acef4f960b3b933ee869a598f31f5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philipp=20Kr=C3=BCger?= Date: Thu, 25 Apr 2024 15:59:00 +0200 Subject: [PATCH] chore: docs --- wnfs/src/private/directory.rs | 23 ++++++++++++++++++++--- wnfs/src/private/file.rs | 12 ++++++++++-- wnfs/src/private/node/header.rs | 3 ++- wnfs/src/private/node/node.rs | 3 ++- 4 files changed, 34 insertions(+), 7 deletions(-) diff --git a/wnfs/src/private/directory.rs b/wnfs/src/private/directory.rs index c34e28b8..734ec94c 100644 --- a/wnfs/src/private/directory.rs +++ b/wnfs/src/private/directory.rs @@ -422,7 +422,12 @@ impl PrivateDirectory { Ok(cloned) } - /// TODO(matheus23): DOCS + /// Call this function to prepare this directory for conflict reconciliation merge changes. + /// Advances this node to the revision given in `target_header`. + /// Generates another previous link, unless this node is already a merge node, then this + /// simply updates all previous links to use the correct steps back. + /// Merge nodes preferably just grow in size. This allows them to combine more nicely + /// without causing further conflicts. pub(crate) fn prepare_next_merge<'a>( self: &'a mut Arc, current_cid: Cid, @@ -840,7 +845,10 @@ impl PrivateDirectory { .as_dir() } - /// TODO(matheus23): DOCS + /// Like `search_latest`, but does a linear search and picks up any + /// writes that may need to be reconciled in the process. + /// If it finds that there's multiple concurrent writes to reconcile, then + /// it creates a merged directory and returns that. pub async fn search_latest_reconciled( self: Arc, forest: &impl PrivateForest, @@ -1358,7 +1366,16 @@ impl PrivateDirectory { PrivateNode::Dir(Arc::clone(self)) } - /// TODO(matheus23): DOCS + /// Merges two directories that have been stored before together + /// (their CIDs must be passed in). + /// This only merges the directories shallowly. It doesn't recursively merge + /// them. This is handled by directories calling `search_latest_reconciled` + /// on every level. + /// Every directory should have a corresponding "identity directory" which is the + /// empty directory, which when merged, results in no change. + /// This function is both commutative and associative. + /// If there's a conflict, it prefers keeping the directory, then tie-breaks on + /// the private ref. pub(crate) async fn merge( self: &mut Arc, target_header: PrivateNodeHeader, diff --git a/wnfs/src/private/file.rs b/wnfs/src/private/file.rs index 3be594aa..21b5aeb2 100644 --- a/wnfs/src/private/file.rs +++ b/wnfs/src/private/file.rs @@ -753,7 +753,12 @@ impl PrivateFile { Ok(cloned) } - /// TODO(matheus23): DOCS + /// Call this function to prepare this file for conflict reconciliation merge changes. + /// Advances this node to the revision given in `target_header`. + /// Generates another previous link, unless this node is already a merge node, then this + /// simply updates all previous links to use the correct steps back. + /// Merge nodes preferably just grow in size. This allows them to combine more nicely + /// without causing further conflicts. pub(crate) fn prepare_next_merge<'a>( self: &'a mut Arc, current_cid: Cid, @@ -875,7 +880,10 @@ impl PrivateFile { PrivateNode::File(Arc::clone(self)) } - /// TODO(matheus23): DOCS + /// Merges two private files together. + /// The files must have been stored before (that's the CIDs that + /// are passed in). + /// This function is both commutative and associative. pub(crate) fn merge( self: &mut Arc, target_header: PrivateNodeHeader, diff --git a/wnfs/src/private/node/header.rs b/wnfs/src/private/node/header.rs index e5cf488d..2731b60a 100644 --- a/wnfs/src/private/node/header.rs +++ b/wnfs/src/private/node/header.rs @@ -216,7 +216,8 @@ impl PrivateNodeHeader { Ok(header) } - /// TODO(matheus23): DOCS + /// Returns the multivalue of nodes (and their corresponding CIDs) from + /// the forest at this header's revision. pub(crate) async fn get_multivalue( &self, forest: &impl PrivateForest, diff --git a/wnfs/src/private/node/node.rs b/wnfs/src/private/node/node.rs index 58e34e1b..76b2f6cb 100644 --- a/wnfs/src/private/node/node.rs +++ b/wnfs/src/private/node/node.rs @@ -418,7 +418,8 @@ impl PrivateNode { } } - /// TODO(matheus23): DOCS + /// Merges a non-empty set of conflicting private nodes together + /// by merging them pair-wise. pub(crate) async fn merge( header: PrivateNodeHeader, (cid, node): (Cid, PrivateNode),