From 311599e8f23e7b4a8fc8a3e06b166f5193759891 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Thu, 23 Jul 2026 22:50:55 +0200
Subject: [PATCH] docs(#2671): trim per-verb arg help (diff, list, lint,
 pr-merge)

Continue trimming clap arg help to user-relevant info: drop the
token-bounded-paging rationale (list --page), the why-it's-required
note (lint no-reviewer), the `Forgejo Do:`/`force_merge` API internals
(pr-merge), and tighten diff --full. pr-status was already clean.
---
 hive-forge/src/verbs/diff.rs     |  7 +++----
 hive-forge/src/verbs/lint.rs     |  6 ++----
 hive-forge/src/verbs/list.rs     |  8 ++------
 hive-forge/src/verbs/pr_merge.rs | 10 ++++------
 4 files changed, 11 insertions(+), 20 deletions(-)

diff --git a/hive-forge/src/verbs/diff.rs b/hive-forge/src/verbs/diff.rs
index 17bdebe1..1aed2c2e 100644
--- a/hive-forge/src/verbs/diff.rs
+++ b/hive-forge/src/verbs/diff.rs
@@ -23,10 +23,9 @@ use crate::client::{Client, index};
 pub struct Args {
     /// PR number.
     number: u64,
-    /// Print the unfiltered diff including autogenerated-file
-    /// hunks (`flake.lock`, `Cargo.lock`, etc.). Default is to
-    /// collapse those hunks to a placeholder so the human-authored
-    /// changes aren't drowned in lock churn.
+    /// Print the unfiltered diff. By default, autogenerated-file hunks
+    /// (`flake.lock`, `Cargo.lock`, …) are collapsed to a placeholder so
+    /// human-authored changes stay readable.
     #[arg(long)]
     full: bool,
 }
diff --git a/hive-forge/src/verbs/lint.rs b/hive-forge/src/verbs/lint.rs
index be7d378a..079fd253 100644
--- a/hive-forge/src/verbs/lint.rs
+++ b/hive-forge/src/verbs/lint.rs
@@ -109,10 +109,8 @@ struct NoReviewerArgs {
     /// Filter by PR state.
     #[arg(long, value_enum, default_value_t = State::Open)]
     state: State,
-    /// Reviewer login to look for (matches `@<reviewer>` in PR body or
-    /// any comment). Required — defaulting to a specific name would
-    /// bake one deployment's reviewer convention into the binary
-    /// (flagged in review).
+    /// Reviewer login to look for (matches `@<reviewer>` in the PR body
+    /// or any comment).
     #[arg(long)]
     reviewer: String,
 }
diff --git a/hive-forge/src/verbs/list.rs b/hive-forge/src/verbs/list.rs
index 471da239..a3da678c 100644
--- a/hive-forge/src/verbs/list.rs
+++ b/hive-forge/src/verbs/list.rs
@@ -89,12 +89,8 @@ pub struct Args {
     /// ~50, applies). Must be >= 1.
     #[arg(long, default_value_t = 30, value_parser = clap::value_parser!(u64).range(1..))]
     limit: u64,
-    /// Page number to fetch (1-based; default 1). Combine with `--limit`
-    /// to walk a large result set incrementally — fetch page 1, process,
-    /// fetch page 2, … until a short/empty page. This keeps each call
-    /// token-bounded (one page at a time) instead of pulling a whole
-    /// repo's population into a single response. Must be >= 1 (the forge
-    /// pages are 1-based; page 0 is rejected).
+    /// Page number to fetch (1-based, default 1). Combine with `--limit`
+    /// to page through large result sets incrementally.
     #[arg(long, default_value_t = 1, value_parser = clap::value_parser!(u64).range(1..))]
     page: u64,
 }
diff --git a/hive-forge/src/verbs/pr_merge.rs b/hive-forge/src/verbs/pr_merge.rs
index 884abbb8..ac4c4755 100644
--- a/hive-forge/src/verbs/pr_merge.rs
+++ b/hive-forge/src/verbs/pr_merge.rs
@@ -24,9 +24,9 @@ use crate::client::{Client, index, split_repo};
 /// per-commit history, so a squash option isn't exposed).
 #[derive(Clone, Copy, ValueEnum)]
 pub enum Method {
-    /// Create a merge commit (Forgejo `Do: merge`).
+    /// Create a merge commit.
     Merge,
-    /// Rebase the head branch onto the base then fast-forward (Forgejo `Do: rebase`).
+    /// Rebase the head branch onto the base, then fast-forward.
     Rebase,
 }
 
@@ -56,13 +56,11 @@ pub struct Args {
     /// Merge strategy (default: a merge commit). Squash is not offered.
     #[arg(long, value_enum, default_value = "merge")]
     method: Method,
-    /// Keep the head branch after merging. By default the head branch is
-    /// deleted once the merge succeeds.
+    /// Keep the head branch after merging (deleted by default).
     #[arg(long = "keep-branch")]
     keep_branch: bool,
     /// Merge even if the PR is not mergeable, CI is not green, or a review
-    /// requests changes. Also sets Forgejo's `force_merge` so the server does
-    /// not refuse on its own status checks.
+    /// requests changes.
     #[arg(long)]
     force: bool,
 }