From 17554ea563e8c42593c4d4427f896e05066f0bf3 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 7 Sep 2026 16:09:28 +0200 Subject: [PATCH] fix: sync generated hive-forge CLI docs with their clap source strings Same bug as the swarmctl/hivectl fix, a third instance argus's review didn't name but nix/checks.nix's hive-forge-docs freshness check (same pattern as hivectl-docs/swarmctl-docs) caught in CI: the earlier Contractions/Foreign/Auto batches edited docs/tools/forge-cli.md directly instead of the clap #[arg(...)]/doc-comment strings in hive-forge/src/main.rs and hive-forge/src/verbs/*.rs. Applied the same 13 wording changes to source that the earlier commits already made to the generated .md, matched 1:1 against 'git diff origin/main HEAD -- docs/tools/forge-cli.md' rather than guessed. Several source doc comments feed two rendered sections each (e.g. reaction.rs's one Add-variant doc renders under both 'issue reaction add' and 'pr reaction add', since both subcommands share the same enum) -- one source fix, two generated-doc fixes. Regenerated from the now-fixed source and confirmed byte-identical to what's already committed (diff exit 0) -- source and generated output are back in sync, same as the swarmctl/hivectl fix. cargo clippy -p hive-forge --all-targets -- -D warnings and scripts/check-doc-refs.sh both clean. --- hive-forge/src/main.rs | 2 +- hive-forge/src/verbs/artifact_get.rs | 2 +- hive-forge/src/verbs/attachment_get.rs | 2 +- hive-forge/src/verbs/ci_runs.rs | 2 +- hive-forge/src/verbs/clone.rs | 2 +- hive-forge/src/verbs/issue_create.rs | 2 +- hive-forge/src/verbs/lint.rs | 4 ++-- hive-forge/src/verbs/pr_create.rs | 2 +- hive-forge/src/verbs/pr_merge.rs | 4 ++-- hive-forge/src/verbs/reaction.rs | 2 +- hive-forge/src/verbs/repo_create.rs | 2 +- 11 files changed, 13 insertions(+), 13 deletions(-) diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs index ff5e0aa6..beb555fc 100644 --- a/hive-forge/src/main.rs +++ b/hive-forge/src/main.rs @@ -124,7 +124,7 @@ enum Verb { #[command(hide = true)] PrStatus(verbs::pr_status::Args), /// Clone a forge repo (default `-r`/`HIVE_FORGE_REPO`) with - /// credentials auto-injected. Pairs with `pr-create --agit`. + /// credentials autoinjected. Pairs with `pr-create --agit`. Clone(verbs::clone::Args), /// Create a forge repo under the current user (or `--org`). Prints /// the repo URL. diff --git a/hive-forge/src/verbs/artifact_get.rs b/hive-forge/src/verbs/artifact_get.rs index 59bc4ca9..3ac20986 100644 --- a/hive-forge/src/verbs/artifact_get.rs +++ b/hive-forge/src/verbs/artifact_get.rs @@ -29,7 +29,7 @@ use crate::client::Client; #[derive(ClapArgs)] pub struct Args { - /// Artifact name, as shown on the run page (e.g. `pr1ma-paper-pdf`). + /// Artifact name, as shown on the run page (for example `pr1ma-paper-pdf`). name: String, /// Workflow run number — the `runs/` in the run-page URL, which /// `pr-status` surfaces as a CI context's `target_url`. (This is the diff --git a/hive-forge/src/verbs/attachment_get.rs b/hive-forge/src/verbs/attachment_get.rs index 7d4caef9..8b781050 100644 --- a/hive-forge/src/verbs/attachment_get.rs +++ b/hive-forge/src/verbs/attachment_get.rs @@ -22,7 +22,7 @@ pub struct Args { /// URL (`http://localhost:3000/attachments/abc-123-...`). attachment: String, /// Output path. Defaults to `/tmp/forge-attachment-`. - /// Pass `-` to write raw bytes to stdout (e.g. for piping to an + /// Pass `-` to write raw bytes to stdout (for example for piping to an /// image viewer). #[arg(short = 'o', long)] output: Option, diff --git a/hive-forge/src/verbs/ci_runs.rs b/hive-forge/src/verbs/ci_runs.rs index ab023438..64200237 100644 --- a/hive-forge/src/verbs/ci_runs.rs +++ b/hive-forge/src/verbs/ci_runs.rs @@ -18,7 +18,7 @@ use crate::verbs::print_json; #[derive(ClapArgs)] pub struct Args { - /// Only runs of this workflow file (e.g. `ci.yml`). + /// Only runs of this workflow file (for example `ci.yml`). #[arg(long)] workflow: Option, /// Only runs on this ref. A branch name (`main`, `damocles/foo`) or a diff --git a/hive-forge/src/verbs/clone.rs b/hive-forge/src/verbs/clone.rs index b0c2a555..1e171ab7 100644 --- a/hive-forge/src/verbs/clone.rs +++ b/hive-forge/src/verbs/clone.rs @@ -24,7 +24,7 @@ use crate::client::Client; #[derive(ClapArgs)] pub struct Args { /// Destination directory. Defaults to the repo's basename - /// (e.g. `internal/knowledge` → `knowledge`). + /// (for example `internal/knowledge` → `knowledge`). dest: Option, /// Branch to check out after cloning. #[arg(long)] diff --git a/hive-forge/src/verbs/issue_create.rs b/hive-forge/src/verbs/issue_create.rs index 5b279455..ee9f36dc 100644 --- a/hive-forge/src/verbs/issue_create.rs +++ b/hive-forge/src/verbs/issue_create.rs @@ -23,7 +23,7 @@ pub struct Args { /// Initial assignee login. #[arg(long)] assignee: Option, - /// Label name to attach, repeatable (e.g. `--label area/ops --label + /// Label name to attach, repeatable (for example `--label area/ops --label /// type/bug`). Same spelling `labels add` accepts. An unresolved name /// errors out (before the issue is created) rather than silently /// attaching fewer labels than asked for. diff --git a/hive-forge/src/verbs/lint.rs b/hive-forge/src/verbs/lint.rs index 4df42ef3..e1b170b5 100644 --- a/hive-forge/src/verbs/lint.rs +++ b/hive-forge/src/verbs/lint.rs @@ -49,7 +49,7 @@ enum Sub { /// Group open issues + PRs by assignee. Assignments(AssignmentsArgs), /// List issues/PRs with no exclusive scoped label in `--scope` - /// (e.g. `--scope type` flags items missing any `type/*` label). + /// (for example `--scope type` flags items missing any `type/*` label). /// Generic — the scope is whatever the repo's label taxonomy /// actually uses, nothing hardcoded here. Unlabeled(UnlabeledArgs), @@ -139,7 +139,7 @@ struct AssignmentsArgs { #[derive(ClapArgs)] struct UnlabeledArgs { /// Label scope to check for — the part of a scoped label's name - /// before the `/` (e.g. `type` for `type/bug`, `type/feature`). + /// before the `/` (for example `type` for `type/bug`, `type/feature`). /// Required: this command has no built-in notion of a repo's label /// taxonomy, so there's no sane default to fall back to. #[arg(long)] diff --git a/hive-forge/src/verbs/pr_create.rs b/hive-forge/src/verbs/pr_create.rs index 905e9b54..56c44520 100644 --- a/hive-forge/src/verbs/pr_create.rs +++ b/hive-forge/src/verbs/pr_create.rs @@ -68,7 +68,7 @@ pub struct Args { /// meaningful with `--agit`. #[arg(long)] topic: Option, - /// Label name to attach, repeatable (e.g. `--label area/ops --label + /// Label name to attach, repeatable (for example `--label area/ops --label /// type/bug`). Same spelling `labels add` accepts — an unresolved name /// errors out rather than silently attaching fewer labels than asked /// for. In `--agit` mode this is applied as a follow-up call once the diff --git a/hive-forge/src/verbs/pr_merge.rs b/hive-forge/src/verbs/pr_merge.rs index cdd99970..fa95597f 100644 --- a/hive-forge/src/verbs/pr_merge.rs +++ b/hive-forge/src/verbs/pr_merge.rs @@ -53,13 +53,13 @@ impl Method { pub struct Args { /// PR number to merge. number: u64, - /// Merge strategy (default: a merge commit). Squash is not offered. + /// Merge strategy (default: a merge commit). Squash isn't offered. #[arg(long, value_enum, default_value = "merge")] method: Method, /// 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 + /// Merge even if the PR isn't mergeable, CI isn't green, or a review /// requests changes. #[arg(long)] force: bool, diff --git a/hive-forge/src/verbs/reaction.rs b/hive-forge/src/verbs/reaction.rs index bde19d12..4a744b8c 100644 --- a/hive-forge/src/verbs/reaction.rs +++ b/hive-forge/src/verbs/reaction.rs @@ -50,7 +50,7 @@ pub struct Args { enum Action { /// List reactions (default when no action is given). List, - /// Add a reaction — a Forgejo shortcode, e.g. `+1`, `heart`, `rocket`. + /// Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`. Add { content: String }, /// Remove your own reaction with this content. Remove { content: String }, diff --git a/hive-forge/src/verbs/repo_create.rs b/hive-forge/src/verbs/repo_create.rs index 2419228b..5197bdb4 100644 --- a/hive-forge/src/verbs/repo_create.rs +++ b/hive-forge/src/verbs/repo_create.rs @@ -27,7 +27,7 @@ pub struct Args { /// Create the repo as private (default: public). #[arg(long)] private: bool, - /// Default branch name (e.g. `main`). Only takes effect with `--auto-init`. + /// Default branch name (for example `main`). Only takes effect with `--auto-init`. #[arg(long = "default-branch")] default_branch: Option, /// Create under this organisation instead of your own namespace.