improve document and comment

crates/signed_state/src/backend.rs

@@ -245,9 +245,8 @@ impl Backend {
     /// Decrypt the NIP-49 encrypted credential stored in the keyring with
     /// the given passphrase and resume the session.
     ///
-    /// The scrypt decryption runs off the UI thread. The returned task
-    /// yields the public key on success, or the failure reason (e.g. wrong
-    /// passphrase), so callers can render inline errors.
+    /// The scrypt decryption runs off the UI thread. The task yields the
+    /// public key, or the failure reason (e.g. wrong passphrase).
     pub fn restore_with_passphrase(
         &mut self,
         password: &str,
@@ -286,9 +285,8 @@ impl Backend {
     /// passphrase (NIP-49) and persist it in the keyring, then publish the
     /// user's NIP-65 relay list, metadata and grasp list.
     ///
-    /// The heavy encryption runs off the UI thread. The returned task yields
-    /// the new public key on success, or the failure reason, so callers can
-    /// render progress and inline errors.
+    /// The encryption runs off the UI thread; the task yields the new
+    /// public key.
     pub fn create_identity(
         &mut self,
         name: &str,
@@ -386,11 +384,8 @@ impl Backend {
     /// a push for a not-yet-existing repository while that authorization is
     /// pending (it expires after 30 minutes), like gitworkshop and ngit.
     ///
-    /// The git work (init, commit, push) runs on background threads. The
-    /// returned task yields the published announcement on success, so
-    /// callers can open the new repository right away. The announcement's
-    /// `relays` tag carries the grasp servers, which are also added to the
-    /// relay pool so the published events reach them.
+    /// The git work runs on background threads; the task yields the
+    /// published announcement.
     pub fn create_repository(
         &mut self,
         name: &str,
@@ -435,8 +430,7 @@ impl Backend {
         let servers = grasp_servers.clone();
 
         cx.spawn(async move |this, cx| {
-            // 1. Initialize the local clone (main branch + README + initial
-            //    commit) on a background thread.
+            // Initialize the local clone (main branch + README + initial commit).
             let work = cx.background_spawn({
                 let path = path.clone();
                 let name = name.clone();
@@ -467,16 +461,14 @@ impl Backend {
             let commit_sha =
                 Sha1Hash::from_str(&commit).map_err(|_| anyhow!("invalid initial commit id"))?;
 
-            // 2. Ensure the grasp servers are in the relay pool; the nostr
-            //    client queues events until each relay is connected.
+            // The nostr client queues events until each relay is connected.
             this.update(cx, |this, cx| {
                 let urls: Vec<String> = servers.iter().map(ToString::to_string).collect();
                 this.add_relays(urls, cx);
             })?;
 
-            // 3. Publish the announcement, then the state event, to the
-            //    grasp relays. The state event is the push authorization
-            //    ("purgatory"), so it must be accepted before step 4.
+            // The state event is the push authorization ("purgatory"), so
+            // it must be accepted before the push below.
             let announcement = GitRepositoryAnnouncement {
                 id: repo_id.clone(),
                 name: Some(name.clone()),
@@ -522,9 +514,8 @@ impl Backend {
                 }
             };
 
-            // 4. Push the initial commit to every grasp server. A server
-            //    that fails to accept the push is logged, but the creation
-            //    only fails when no server accepted it.
+            // Push to every grasp server; creation only fails when no
+            // server accepted it.
             let push = cx.background_spawn({
                 let path = path.clone();
                 let owner = owner.clone();
@@ -555,14 +546,8 @@ impl Backend {
     /// state to the grasp relays, then push every branch and tag to each
     /// grasp server. Also points `origin` at the first grasp server.
     ///
-    /// The events must reach the grasp servers *before* the push, like
-    /// [`Self::create_repository`]: GRASP servers hold the signed state
-    /// event in "purgatory" and only accept a push while that
-    /// authorization is pending.
-    ///
-    /// The git work (ref listing, push) runs on background threads. The
-    /// returned task yields the published announcement on success, so
-    /// callers can switch the repository into its NIP-34 mode.
+    /// Same ordering constraint as [`Self::create_repository`]: the state
+    /// event ("purgatory") must be accepted before the push.
     pub fn publish_local_repo(
         &mut self,
         path: PathBuf,
@@ -586,9 +571,8 @@ impl Backend {
             return Task::ready(Err(anyhow!("Sign in to publish a repository")));
         };
 
-        // The repository identifier is derived from the name, like
-        // [`Self::create_repository`]: spaces become hyphens, other
-        // non-alphanumeric characters (except `/`) become hyphens.
+        // The repository identifier is derived from the name as in
+        // [`Self::create_repository`].
         let repo_id = identifier_from_name(&name);
 
         if repo_id.is_empty() || repo_id.len() > 100 {
@@ -607,8 +591,6 @@ impl Backend {
         let servers = grasp_servers.clone();
 
         cx.spawn(async move |this, cx| {
-            // 1. Read the local repository's refs (branches, tags, HEAD)
-            //    and its root commit on a background thread.
             let work = cx.background_spawn({
                 let path = path.clone();
                 async move {
@@ -619,16 +601,14 @@ impl Backend {
             });
             let (state, euc) = work.await?;
 
-            // 2. Ensure the grasp servers are in the relay pool; the nostr
-            //    client queues events until each relay is connected.
+            // The nostr client queues events until each relay is connected.
             this.update(cx, |this, cx| {
                 let urls: Vec<String> = servers.iter().map(ToString::to_string).collect();
                 this.add_relays(urls, cx);
             })?;
 
-            // 3. Publish the announcement, then the state event, to the
-            //    grasp relays. The state event is the push authorization
-            //    ("purgatory"), so it must be accepted before step 4.
+            // The state event is the push authorization ("purgatory"), so
+            // it must be accepted before the push below.
             let announcement = GitRepositoryAnnouncement {
                 id: repo_id.clone(),
                 name: Some(name.clone()),
@@ -672,10 +652,9 @@ impl Backend {
                 }
             };
 
-            // 4. Push every branch and tag to each grasp server. A server
-            //    that fails to accept the push is logged, but the init only
-            //    fails when no server accepted it. An empty repository
-            //    (no refs yet) has nothing to push.
+            // Push every branch and tag to each grasp server; the init
+            // only fails when no server accepted it. An empty repository
+            // has nothing to push.
             if !refs.is_empty() {
                 let push = cx.background_spawn({
                     let path = path.clone();
@@ -697,8 +676,8 @@ impl Backend {
                 }
             }
 
-            // 5. Point `origin` at the first grasp server so later pushes
-            //    have a target, like the create flow.
+            // Point `origin` at the first grasp server so later pushes
+            // have a target.
             if let Some(base) = servers.first().and_then(grasp_base_url) {
                 let url = format!("{base}/{owner}/{repo_id}.git");
                 let path = path.clone();
@@ -732,15 +711,13 @@ impl Backend {
         let relays = announcement.relays.clone();
 
         cx.spawn(async move |this, cx| {
-            // 1. Read the current refs of the local clone.
             let work = cx.background_spawn({
                 let path = path.clone();
                 async move { signed_git::worktree_ref_state(&path) }
             });
             let state = work.await?;
 
-            // 2. Publish a fresh state event; grasp servers authorize a
-            //    push by the state they have seen.
+            // Grasp servers authorize a push by the state they have seen.
             let refs = state.refs.clone();
             let head = state.head.clone();
             this.update(cx, |this, cx| {
@@ -749,7 +726,6 @@ impl Backend {
             })?
             .await?;
 
-            // 3. Push every branch and tag to the announced grasp servers.
             if !refs.is_empty() {
                 let push = cx.background_spawn({
                     let path = path.clone();
@@ -1111,9 +1087,8 @@ impl Backend {
     /// `filters`, plus a negentropy sync so issues, patches and PRs stored
     /// only on those relays are not missed.
     ///
-    /// Best-effort: failures are logged, not surfaced, because the bootstrap
-    /// relays already cover the repository. The relays stay in the pool, so
-    /// events the user publishes for this repository also reach them.
+    /// Best-effort: failures are logged, not surfaced. The relays stay in
+    /// the pool, so later publishes for this repository also reach them.
     pub fn connect_repo_relays(
         &mut self,
         relays: Vec<RelayUrl>,
@@ -1221,10 +1196,9 @@ impl Backend {
     /// Sign, broadcast and locally store an event. Emits
     /// [`BackendEvent::Published`] on success so stores can refresh.
     ///
-    /// The returned task yields the outcome of this specific action, so
-    /// callers can show inline progress/errors instead of relying on
-    /// the global [`BackendEvent::Error`]. The task is owned by the caller;
-    /// dropping it cancels the publish.
+    /// The task yields the outcome of this specific action (for inline
+    /// progress/errors) and is owned by the caller; dropping it cancels
+    /// the publish.
     pub fn send(
         &mut self,
         builder: EventBuilder,

crates/signed_state/src/lib.rs

@@ -34,7 +34,6 @@ pub fn init(db_path: impl AsRef<Path>, cx: &mut App) -> Entity<Backend> {
         .install_default()
         .ok();
 
-    // Initialize the nostr client and universal signer.
     let (client, signer) = cx.foreground_executor().block_on(async move {
         let path = db_path.as_ref().to_path_buf();
         new_backend(path)
@@ -42,24 +41,18 @@ pub fn init(db_path: impl AsRef<Path>, cx: &mut App) -> Entity<Backend> {
             .expect("failed to initialize nostr backend")
     });
 
-    // Initialize the backend and stores.
     let entity = cx.new(|cx| Backend::new(client, signer, cx));
     Backend::set_global(entity.clone(), cx);
-
-    // Initialize the profile store.
     ProfileStore::set_global(cx.new(ProfileStore::new), cx);
 
-    // Start the explore list from the local database before
-    // the first window opens, relay syncs continue in the background,
-    // so the list never waits for them.
+    // Seed the explore list from the local database; relay syncs continue
+    // in the background.
     RepoListStore::set_global(cx.new(|cx| RepoListStore::new(None, cx)), cx);
 
-    // The clone cache is only meaningful on native platforms,
-    // the wasm build registers an empty store so `GitStore::global` still works.
+    // The clone cache is native-only; wasm registers an empty store so
+    // `GitStore::global` still works.
     GitStore::set_global(PathBuf::new(), cx);
 
-    // Scan the default directories (Desktop, Documents) for local git
-    // repositories; the sidebar lists them next to the user's NIP-34 repos.
     LocalReposStore::set_global(
         cx.new(|cx| LocalReposStore::new(default_scan_paths(), cx)),
         cx,
@@ -71,26 +64,13 @@ pub fn init(db_path: impl AsRef<Path>, cx: &mut App) -> Entity<Backend> {
 /// Initialize the backend with an in-memory database on wasm.
 #[cfg(target_arch = "wasm32")]
 pub fn init(cx: &mut App) -> Entity<Backend> {
-    // Initialize the nostr client and universal signer.
     let (client, signer) = new_backend().expect("failed to initialize nostr backend");
 
-    // Initialize the backend and stores.
     let entity = cx.new(|cx| Backend::new(client, signer, cx));
     Backend::set_global(entity.clone(), cx);
-
-    // Initialize the profile store.
     ProfileStore::set_global(cx.new(ProfileStore::new), cx);
-
-    // Start the explore list from the local database before
-    // the first window opens, relay syncs continue in the background,
-    // so the list never waits for them.
     RepoListStore::set_global(cx.new(|cx| RepoListStore::new(None, cx)), cx);
-
-    // The clone cache is only meaningful on native platforms,
-    // the wasm build registers an empty store so `GitStore::global` still works.
     GitStore::set_global(PathBuf::new(), cx);
-
-    // No filesystem scan on wasm: there are no local git repositories.
     LocalReposStore::set_global(cx.new(|cx| LocalReposStore::new(Vec::new(), cx)), cx);
 
     entity

crates/signed_state/src/repo.rs

@@ -586,15 +586,12 @@ impl RepoStore {
     /// (kind 1617) carrying the `git format-patch` output, which the PR
     /// references via an `e` tag (NIP-34).
     ///
-    /// The patch is published first and the PR is sent once the patch
-    /// event's id is known, so the two always arrive together. The proposed
-    /// commit is parsed from the patch's `From <commit>` header; publishing
-    /// without one is refused, because the PR's `c` tag (and the patch's
-    /// `commit`/`r` tags) must carry a real commit id for other NIP-34
-    /// clients to verify and apply the proposal. The PR's `clone` tag
-    /// carries the repository's announced mirror URLs (the commit may not be
-    /// pushed there yet; the linked patch is the source of truth until a
-    /// push backend exists).
+    /// The patch is published first so the PR can reference its id. The
+    /// proposed commit is parsed from the patch's `From <commit>` header;
+    /// without one publishing is refused, because the PR's `c` tag must
+    /// carry a real commit id for other NIP-34 clients to verify and apply
+    /// the proposal. The `clone` tag carries the announced mirror URLs; the
+    /// linked patch is the source of truth until the commit is pushed there.
     pub fn open_pull_request(
         &mut self,
         subject: Option<String>,
@@ -783,10 +780,9 @@ impl RepoStore {
     /// the merged status.
     ///
     /// Only the repository author may merge. The clone is created on demand
-    /// from the announcement's clone URLs when the repository hasn't been
-    /// mirrored locally yet. Patch application runs on a background thread
-    /// (`git am`); failures (e.g. a patch that no longer applies) surface in
-    /// [`Self::last_error`] and no status is sent.
+    /// from the announcement's clone URLs when needed. Patch application
+    /// (`git am`) runs on a background thread; failures (e.g. a patch that
+    /// no longer applies) surface in [`Self::last_error`].
     pub fn merge_pull_request(&mut self, root: &Event, cx: &mut Context<Self>) {
         self.last_error = None;
 
@@ -876,12 +872,10 @@ fn patch_current_commit(patch: &str) -> Option<&str> {
     hex.split_whitespace().next().filter(|hex| hex.len() == 40)
 }
 
-/// Build a NIP-22 kind-1111 comment using the SDK's [`CommentBuilder`]:
-/// uppercase `E`/`K`/`P` tags scope the thread root, lowercase `e`/`k`/`p`
-/// tags the direct parent (`parent`, or the root itself for a top-level
-/// comment). An `a` tag with the repository coordinate is added so Signed's
-/// own activity subscriptions also match the comment (it is not part of
-/// NIP-22).
+/// Build a NIP-22 kind-1111 comment: uppercase `E`/`K`/`P` tags scope the
+/// thread root, lowercase `e`/`k`/`p` the direct parent (or the root for a
+/// top-level comment). An `a` tag with the repository coordinate (not part
+/// of NIP-22) is added so Signed's own activity subscriptions also match.
 fn comment_builder(
     root: &Event,
     parent: Option<&Event>,

crates/signed_state/src/repo_list.rs

@@ -22,8 +22,7 @@ impl Global for GlobalRepoListStore {}
 
 /// Counts of NIP-34 activity events per repository, used to rank the
 /// explore list by popularity. Each patch event is a pushed commit (or a
-/// small commit series), which is the closest cross-repository proxy for
-/// commit count available from event data alone.
+/// small series), the closest proxy for commit count in the event data.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct RepoActivityCounts {
     /// Root `30611` issue events addressed to the repository.