From 1195bfbe11d6c676fb3fb4388db767a3128af539 Mon Sep 17 00:00:00 2001 From: damocles Date: Sun, 31 May 2026 15:57:19 +0200 Subject: [PATCH] hive-forge: add # Errors docs on every verb's pub fn run (closes #816) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit systemic gap argus flagged on PR #798 (timeline verb). every `pub fn run` in hive-forge/src/verbs/*.rs lacked a `# Errors` block — violates Rust API guidelines + obscures the failure surface for operators reading the source. uniform doc per verb category: - pure GET + print verbs: "transport error from the Forgejo REST call + I/O error from stdout" - body-from-file verbs (comment/comment_edit/issue_create/issue_edit/ pr_create): adds 'I/O error from --body-file/stdin input' - file-upload verbs (attach-issue, attach-comment): adds 'file read/exist check' - pr_create: also mentions the --push shellout 23 `pub fn run` signatures touched. no behaviour change; pure documentation sweep. cargo test green (38 tests). --- hive-forge/src/verbs/assign.rs | 5 +++++ hive-forge/src/verbs/attach.rs | 12 ++++++++++++ hive-forge/src/verbs/branches.rs | 5 +++++ hive-forge/src/verbs/close.rs | 5 +++++ hive-forge/src/verbs/comment.rs | 6 ++++++ hive-forge/src/verbs/comment_edit.rs | 6 ++++++ hive-forge/src/verbs/comment_show.rs | 5 +++++ hive-forge/src/verbs/comments.rs | 5 +++++ hive-forge/src/verbs/diff.rs | 5 +++++ hive-forge/src/verbs/issue.rs | 5 +++++ hive-forge/src/verbs/issue_create.rs | 6 ++++++ hive-forge/src/verbs/issue_edit.rs | 6 ++++++ hive-forge/src/verbs/labels.rs | 5 +++++ hive-forge/src/verbs/lint.rs | 7 +++++++ hive-forge/src/verbs/list.rs | 5 +++++ hive-forge/src/verbs/milestone.rs | 5 +++++ hive-forge/src/verbs/pr.rs | 5 +++++ hive-forge/src/verbs/pr_create.rs | 7 +++++++ hive-forge/src/verbs/pr_reviews.rs | 5 +++++ hive-forge/src/verbs/subscription.rs | 5 +++++ hive-forge/src/verbs/timeline.rs | 5 +++++ hive-forge/src/verbs/tree_sha.rs | 5 +++++ hive-forge/src/verbs/view.rs | 5 +++++ 23 files changed, 130 insertions(+) diff --git a/hive-forge/src/verbs/assign.rs b/hive-forge/src/verbs/assign.rs index 5c9ed713..8b7044db 100644 --- a/hive-forge/src/verbs/assign.rs +++ b/hive-forge/src/verbs/assign.rs @@ -21,6 +21,11 @@ pub struct Args { remove: bool, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let current = client.get_json(&format!("/repos/{repo}/issues/{}", args.number))?; diff --git a/hive-forge/src/verbs/attach.rs b/hive-forge/src/verbs/attach.rs index 91e621ba..a7d60eee 100644 --- a/hive-forge/src/verbs/attach.rs +++ b/hive-forge/src/verbs/attach.rs @@ -26,6 +26,12 @@ pub struct CommentArgs { file: PathBuf, } +/// # Errors +/// +/// Returns an error if the input file doesn't exist or can't be +/// read. Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the browser download URL to stdout. pub fn run_issue(client: &Client, args: IssueArgs) -> Result<()> { if !args.file.is_file() { bail!( @@ -42,6 +48,12 @@ pub fn run_issue(client: &Client, args: IssueArgs) -> Result<()> { Ok(()) } +/// # Errors +/// +/// Returns an error if the input file doesn't exist or can't be +/// read. Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the browser download URL to stdout. pub fn run_comment(client: &Client, args: CommentArgs) -> Result<()> { if !args.file.is_file() { bail!( diff --git a/hive-forge/src/verbs/branches.rs b/hive-forge/src/verbs/branches.rs index 287f5024..8f590fae 100644 --- a/hive-forge/src/verbs/branches.rs +++ b/hive-forge/src/verbs/branches.rs @@ -12,6 +12,11 @@ pub struct Args { pattern: Option, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let v = client.get_json(&format!("/repos/{repo}/branches?limit=100"))?; diff --git a/hive-forge/src/verbs/close.rs b/hive-forge/src/verbs/close.rs index 0d01ce27..58fb2037 100644 --- a/hive-forge/src/verbs/close.rs +++ b/hive-forge/src/verbs/close.rs @@ -13,6 +13,11 @@ pub struct Args { number: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let resp = client.patch_json( diff --git a/hive-forge/src/verbs/comment.rs b/hive-forge/src/verbs/comment.rs index e2aece1a..2a99a380 100644 --- a/hive-forge/src/verbs/comment.rs +++ b/hive-forge/src/verbs/comment.rs @@ -21,6 +21,12 @@ pub struct Args { body_file: Option, } +/// # Errors +/// +/// Propagates any I/O error from the body input (`--body-file`, +/// stdin), any transport error from the Forgejo REST call (network +/// unreachable, 4xx/5xx response, token missing/invalid), and any +/// I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let body = body::resolve_required(args.body.as_deref(), args.body_file.as_deref(), "comment")?; let repo = client.repo(); diff --git a/hive-forge/src/verbs/comment_edit.rs b/hive-forge/src/verbs/comment_edit.rs index c271a399..a2c9aaaf 100644 --- a/hive-forge/src/verbs/comment_edit.rs +++ b/hive-forge/src/verbs/comment_edit.rs @@ -21,6 +21,12 @@ pub struct Args { body_file: Option, } +/// # Errors +/// +/// Propagates any I/O error from the body input (`--body-file`, +/// stdin), any transport error from the Forgejo REST call (network +/// unreachable, 4xx/5xx response, token missing/invalid), and any +/// I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let body = body::resolve_required( args.body.as_deref(), diff --git a/hive-forge/src/verbs/comment_show.rs b/hive-forge/src/verbs/comment_show.rs index 65e6e8bb..a45ea2e4 100644 --- a/hive-forge/src/verbs/comment_show.rs +++ b/hive-forge/src/verbs/comment_show.rs @@ -14,6 +14,11 @@ pub struct Args { id: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let v = client.get_json(&format!("/repos/{repo}/issues/comments/{}", args.id))?; diff --git a/hive-forge/src/verbs/comments.rs b/hive-forge/src/verbs/comments.rs index f27e3047..24eff13d 100644 --- a/hive-forge/src/verbs/comments.rs +++ b/hive-forge/src/verbs/comments.rs @@ -45,6 +45,11 @@ pub struct Args { tail: Option, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let comments = match args.tail { diff --git a/hive-forge/src/verbs/diff.rs b/hive-forge/src/verbs/diff.rs index 066e0dfc..8b72ffe0 100644 --- a/hive-forge/src/verbs/diff.rs +++ b/hive-forge/src/verbs/diff.rs @@ -30,6 +30,11 @@ pub struct Args { full: bool, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let diff = client.get_text(&format!("/repos/{repo}/pulls/{}.diff", args.number), "text/plain")?; diff --git a/hive-forge/src/verbs/issue.rs b/hive-forge/src/verbs/issue.rs index fdca71db..905ab817 100644 --- a/hive-forge/src/verbs/issue.rs +++ b/hive-forge/src/verbs/issue.rs @@ -13,6 +13,11 @@ pub struct Args { number: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let v = client.get_json(&format!("/repos/{repo}/issues/{}", args.number))?; diff --git a/hive-forge/src/verbs/issue_create.rs b/hive-forge/src/verbs/issue_create.rs index b80fc027..e785bd0d 100644 --- a/hive-forge/src/verbs/issue_create.rs +++ b/hive-forge/src/verbs/issue_create.rs @@ -24,6 +24,12 @@ pub struct Args { assignee: Option, } +/// # Errors +/// +/// Propagates any I/O error from the body input (`--body-file`, +/// stdin), any transport error from the Forgejo REST call (network +/// unreachable, 4xx/5xx response, token missing/invalid), and any +/// I/O error from writing the issue URL to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let body = body::resolve(args.body.as_deref(), args.body_file.as_deref())?.unwrap_or_default(); let repo = client.repo(); diff --git a/hive-forge/src/verbs/issue_edit.rs b/hive-forge/src/verbs/issue_edit.rs index ac761624..9a891199 100644 --- a/hive-forge/src/verbs/issue_edit.rs +++ b/hive-forge/src/verbs/issue_edit.rs @@ -46,6 +46,12 @@ pub struct Args { milestone: Option, } +/// # Errors +/// +/// Propagates any I/O error from the body input (`--body-file`, +/// stdin), any transport error from the Forgejo REST call (network +/// unreachable, 4xx/5xx response, token missing/invalid), and any +/// I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { // Body is partial: only update the body field if a source was // actually given. Piped stdin without --body/--body-file leaves diff --git a/hive-forge/src/verbs/labels.rs b/hive-forge/src/verbs/labels.rs index a0346750..da03212d 100644 --- a/hive-forge/src/verbs/labels.rs +++ b/hive-forge/src/verbs/labels.rs @@ -32,6 +32,11 @@ enum Action { }, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); match args.action.unwrap_or(Action::List) { diff --git a/hive-forge/src/verbs/lint.rs b/hive-forge/src/verbs/lint.rs index af24ffac..b2ed399c 100644 --- a/hive-forge/src/verbs/lint.rs +++ b/hive-forge/src/verbs/lint.rs @@ -116,6 +116,13 @@ struct AssignmentsArgs { user: Option, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. Subcommand +/// dispatches go through the same per-query helpers and inherit +/// the same surfaces. pub fn run(client: &Client, args: Args) -> Result<()> { match args.sub { Sub::Unassigned(a) => run_unassigned(client, a), diff --git a/hive-forge/src/verbs/list.rs b/hive-forge/src/verbs/list.rs index 605858f9..0f96053b 100644 --- a/hive-forge/src/verbs/list.rs +++ b/hive-forge/src/verbs/list.rs @@ -86,6 +86,11 @@ pub struct Args { limit: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let mut path = format!( diff --git a/hive-forge/src/verbs/milestone.rs b/hive-forge/src/verbs/milestone.rs index 5ce9000a..b476b711 100644 --- a/hive-forge/src/verbs/milestone.rs +++ b/hive-forge/src/verbs/milestone.rs @@ -37,6 +37,11 @@ enum Action { }, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); match args.action.unwrap_or(Action::List) { diff --git a/hive-forge/src/verbs/pr.rs b/hive-forge/src/verbs/pr.rs index a3e101af..282041f6 100644 --- a/hive-forge/src/verbs/pr.rs +++ b/hive-forge/src/verbs/pr.rs @@ -13,6 +13,11 @@ pub struct Args { number: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let v = client.get_json(&format!("/repos/{repo}/pulls/{}", args.number))?; diff --git a/hive-forge/src/verbs/pr_create.rs b/hive-forge/src/verbs/pr_create.rs index 3449ac9e..92d1376f 100644 --- a/hive-forge/src/verbs/pr_create.rs +++ b/hive-forge/src/verbs/pr_create.rs @@ -51,6 +51,13 @@ pub struct Args { remote: String, } +/// # Errors +/// +/// Propagates any I/O error from the body input (`--body-file`, +/// stdin) or the `--push` shellout to git, any transport error from +/// the Forgejo REST call (network unreachable, 4xx/5xx response, +/// token missing/invalid), and any I/O error from writing the PR +/// URL to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let body = body::resolve(args.body.as_deref(), args.body_file.as_deref())?.unwrap_or_default(); if args.push { diff --git a/hive-forge/src/verbs/pr_reviews.rs b/hive-forge/src/verbs/pr_reviews.rs index dbf95772..cb9f8387 100644 --- a/hive-forge/src/verbs/pr_reviews.rs +++ b/hive-forge/src/verbs/pr_reviews.rs @@ -13,6 +13,11 @@ pub struct Args { number: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let v = client.get_json(&format!("/repos/{repo}/pulls/{}/reviews", args.number))?; diff --git a/hive-forge/src/verbs/subscription.rs b/hive-forge/src/verbs/subscription.rs index 8fc16d63..08016d13 100644 --- a/hive-forge/src/verbs/subscription.rs +++ b/hive-forge/src/verbs/subscription.rs @@ -21,6 +21,11 @@ pub struct Args { unwatch: bool, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); if args.unwatch { diff --git a/hive-forge/src/verbs/timeline.rs b/hive-forge/src/verbs/timeline.rs index 52c35f1e..d29bed53 100644 --- a/hive-forge/src/verbs/timeline.rs +++ b/hive-forge/src/verbs/timeline.rs @@ -32,6 +32,11 @@ pub struct Args { limit: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let v = client.get_json(&format!( diff --git a/hive-forge/src/verbs/tree_sha.rs b/hive-forge/src/verbs/tree_sha.rs index e2599c9d..29fd98e6 100644 --- a/hive-forge/src/verbs/tree_sha.rs +++ b/hive-forge/src/verbs/tree_sha.rs @@ -13,6 +13,11 @@ pub struct Args { reference: String, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); // Try branch first; the bash helper silently treats failure as diff --git a/hive-forge/src/verbs/view.rs b/hive-forge/src/verbs/view.rs index 01494cdc..53e0719c 100644 --- a/hive-forge/src/verbs/view.rs +++ b/hive-forge/src/verbs/view.rs @@ -13,6 +13,11 @@ pub struct Args { number: u64, } +/// # Errors +/// +/// Propagates any transport error from the Forgejo REST call +/// (network unreachable, 4xx/5xx response, token missing/invalid) +/// and any I/O error from writing the response to stdout. pub fn run(client: &Client, args: Args) -> Result<()> { let repo = client.repo(); let issue = client.get_json(&format!("/repos/{repo}/issues/{}", args.number))?;