From 050b3acb2e9ee3b51bd07e09b3be3630c751c92d Mon Sep 17 00:00:00 2001
From: Alexis Sellier <self@cloudhead.io>
Date: Mon, 30 Jan 2023 14:28:41 +0100
Subject: [PATCH] Improve storage documentation

---
 radicle/src/storage.rs | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/radicle/src/storage.rs b/radicle/src/storage.rs
index d9208258..b1e877e7 100644
--- a/radicle/src/storage.rs
+++ b/radicle/src/storage.rs
@@ -243,22 +243,28 @@ impl Remote<Verified> {
     }
 }
 
+/// Read-only operations on a storage instance.
 pub trait ReadStorage {
+    /// Get the storage base path.
     fn path(&self) -> &Path;
+    /// Get an identity document of a repository under a given remote.
     fn get(
         &self,
         remote: &RemoteId,
-        proj: Id,
+        rid: Id,
     ) -> Result<Option<identity::Doc<Verified>>, ProjectError>;
+    /// Get the inventory of repositories hosted under this storage.
     fn inventory(&self) -> Result<Inventory, Error>;
 }
 
+/// Allows access to individual storage repositories.
 pub trait WriteStorage: ReadStorage {
     type Repository: WriteRepository;
 
     fn repository(&self, proj: Id) -> Result<Self::Repository, Error>;
 }
 
+/// Allows read-only access to a repository.
 pub trait ReadRepository {
     /// Return the repository id.
     fn id(&self) -> Id;
@@ -330,9 +336,14 @@ pub trait ReadRepository {
     fn identity_doc(&self) -> Result<(Oid, identity::Doc<Unverified>), ProjectError>;
 }
 
+/// Allows read-write access to a repository.
 pub trait WriteRepository: ReadRepository {
+    /// Set the repository head to the canonical branch.
+    /// This computes the head based on the delegate set.
     fn set_head(&self) -> Result<Oid, ProjectError>;
+    /// Sign the repository's refs under the `refs/rad/sigrefs` branch.
     fn sign_refs<G: Signer>(&self, signer: &G) -> Result<SignedRefs<Verified>, Error>;
+    /// Get the underlying git repository.
     fn raw(&self) -> &git2::Repository;
 }