swarm-controller: stop narrating pr review history in doc comments

swarm-controller/src/forge.rs

@@ -58,9 +58,7 @@ pub struct IssueReportRow {
     pub labels: Vec<String>,
     /// All assignees, not just one — forgejo's `Issue::assignee` is a
     /// legacy single-value field; `assignee`**s** (plural) is the real
-    /// multi-assignee list, which this repo's issues actually use (mara,
+    /// multi-assignee list, and this repo's issues do use more than one.
-    /// on review: "i thought you can assign multiple users, why just a
-    /// string?").
     pub assignees: Vec<String>,
     pub html_url: Option<String>,
     /// True if any of this issue's own dependencies is still open — same
@@ -68,8 +66,8 @@ pub struct IssueReportRow {
     /// blocker doesn't count).
     pub blocked: bool,
     /// How many OTHER issues in this same report list this issue as a
-    /// dependency. The reverse of `blocked`, for ranking "fix this one to
+    /// dependency — the reverse of `blocked`. Ranks "fix this one to
-    /// unblock the most other work" — mara's own framing for the field.
+    /// unblock the most other work" highest.
     pub depended_on_by_count: u32,
 }
 
@@ -582,12 +580,13 @@ impl Client {
     }
 
     /// Repos with at least one open issue, as `owner/name` full names —
-    /// the data source for swarm-ui's repo-filter dropdown (mara: "repo
+    /// the data source for swarm-ui's repo-filter dropdown, which lists
-    /// filter should be dropdown (list only repos with open issues)").
+    /// only repos that currently have open issues rather than every repo
-    /// Filtered on `Repository::open_issues_count` from the search result
+    /// the forge hosts. Filtered on `Repository::open_issues_count` from
-    /// itself rather than a follow-up `issue_list_issues` call per repo —
+    /// the search result itself rather than a follow-up
-    /// forgejo's own repo summary already carries that count, so this
+    /// `issue_list_issues` call per repo — forgejo's own repo summary
-    /// stays one request regardless of how many repos exist.
+    /// already carries that count, so this stays one request regardless
+    /// of how many repos exist.
     ///
     /// One search page (forgejo's own default page size) — this binding's
     /// `RepoSearchQuery` has no `page`/`limit` field to page through, unlike
@@ -615,7 +614,7 @@ impl Client {
     /// whole job behind `GET /api/repos/{org}/{repo}/issue-report`. Doing
     /// this resolution client-side (one dependency lookup per issue, on
     /// every page load) doesn't scale, which is the reason this endpoint
-    /// exists at all (iris's own framing on the design thread that led here).
+    /// exists at all rather than swarm-ui resolving it itself per row.
     ///
     /// Forgejo has no bulk or reverse dependency query — the same
     /// limitation `hive-forge issue dependency` hits — so this is still one
@@ -718,8 +717,7 @@ impl Client {
 
     /// [`Self::issue_report`], fanned out over every repo
     /// [`Self::list_repos_with_open_issues`] finds — the default,
-    /// no-repo-filter view (mara: "by default, i want it to not filter by
+    /// no-repo-filter view. Each repo's report is resolved independently and
-    /// repo"). Each repo's report is resolved independently and
     /// concurrently (same `CONCURRENCY` bound as the per-issue dependency
     /// resolution inside `issue_report`, since this is the same
     /// "N independent forge round-trips" shape one level up), then

swarm-controller/src/issue_report.rs

@@ -3,10 +3,9 @@
 //! filtered). See [`crate::forge::Client::issue_report`] and
 //! [`crate::forge::Client::issue_report_all`] for how a row's `blocked` /
 //! `depended_on_by_count` fields are actually computed; this module is
-//! just the HTTP surface over that logic, split out into its own file per
+//! just the HTTP surface over that logic, split out into its own file —
-//! mara's review call on the PR that introduced it (same shape
+//! same shape [`crate::webhook`] already uses: business logic in
-//! [`crate::webhook`] already uses: business logic in
+//! `crate::forge::Client`, the axum handlers next to their own routes.
-//! `crate::forge::Client`, the axum handlers next to their own routes).
 
 use axum::{
     Json,
@@ -17,12 +16,11 @@ use super::{AppState, StatusUnavailable};
 use crate::forge;
 
 /// Repos with at least one open issue, as `owner/name` full names — the
-/// data source for swarm-ui's repo-filter dropdown (mara: "repo filter
+/// data source for swarm-ui's repo-filter dropdown. Not scoped to
-/// should be dropdown (list only repos with open issues)"). Not scoped to
+/// [`forge::CONFIG_ORG`] the way `main.rs`'s `get_config_prs` is: this
-/// [`forge::CONFIG_ORG`] the way `main.rs`'s `get_config_prs` is: mara's
+/// report deliberately covers the whole forge instance, not one org, since
-/// own framing for this issue-report page was "repos cannot be fixed for
+/// the report itself is a general-purpose browsing tool rather than
-/// a hyperhive feature", so this deliberately covers the whole forge
+/// something agent-config-specific.
-/// instance, not one org.
 #[utoipa::path(
     get,
     path = "/api/repos",
@@ -51,9 +49,8 @@ pub async fn get_repos(
 }
 
 /// Every open issue across every repo with at least one — the default,
-/// no-repo-filter view (mara: "by default, i want it to not filter by
+/// no-repo-filter view. See [`get_issue_report`] for the single-repo
-/// repo"). See [`get_issue_report`] for the single-repo counterpart (used
+/// counterpart (used once the dropdown's repo filter is set) and
-/// once the dropdown's repo filter is set) and
 /// [`forge::Client::issue_report_all`] for how the fan-out works.
 #[utoipa::path(
     get,