From bc8f1b3cb896cb609b09123981f898f2f372f088 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 7 Sep 2026 15:51:29 +0200 Subject: [PATCH] fix: sync generated CLI docs with their clap source strings docs/tools/swarmctl-cli.md and docs/tools/hivectl-cli.md are generated (nix/checks.nix's swarmctl-docs/hivectl-docs freshness checks diff a fresh 'markdown-docs' run against the committed copy). The earlier Contractions/Foreign fixes in this branch edited the generated markdown directly instead of the clap #[arg(...)]/doc-comment strings in swarmctl/src/main.rs and hivectl/src/cli.rs -- so CI's freshness check would regenerate the docs from unfixed source and silently undo the fix (found by argus's review). Applied the exact same 13 wording changes to source (5 in swarmctl/src/main.rs, 8 in hivectl/src/cli.rs) that the earlier commits already made to the generated .md, matched 1:1 against 'git diff origin/main HEAD -- docs/tools/{swarmctl,hivectl}-cli.md' rather than guessed. Regenerated both docs from the now-fixed source and confirmed byte-identical to what's already committed (both 'diff <(binary markdown-docs) docs/tools/X-cli.md' exit 0) -- source and generated output are back in sync. cargo clippy -p swarmctl -p hivectl --all-targets -- -D warnings and scripts/check-doc-refs.sh both clean. --- hivectl/src/cli.rs | 22 +++++++++++----------- swarmctl/src/main.rs | 10 +++++----- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/hivectl/src/cli.rs b/hivectl/src/cli.rs index fd9f051c..5a7147d6 100644 --- a/hivectl/src/cli.rs +++ b/hivectl/src/cli.rs @@ -70,7 +70,7 @@ pub enum Cmd { /// hive-wide lives at the top level instead (`list-agents`, /// `restart`/`stop`/`start` with a scope, `quota-enable`). Agent { - /// Agent name (e.g. `damocles`, `iris`). + /// Agent name (for example `damocles`, `iris`). name: String, #[command(subcommand)] cmd: AgentCmd, @@ -112,7 +112,7 @@ pub enum Cmd { /// Prints the nix a peer operator pastes into their swarm config to /// trust and reach this hive. PeerConfig { - /// This hive's WireGuard mesh address (e.g. `10.42.0.1/32`), + /// This hive's WireGuard mesh address (for example `10.42.0.1/32`), /// emitted as `wireguardAddress`. Omit when not running the mesh. #[arg(long)] wg_address: Option, @@ -277,7 +277,7 @@ pub enum ForgeCmd { /// /// Always prints the diff first. `--from forge` resets the local /// checkout to forge main (effective on the next deploy); `--from local` - /// is not supported yet. With no `--from`, prompts for the direction. + /// isn't supported yet. With no `--from`, prompts for the direction. ReconcileConfig { /// Agent whose config branches to reconcile. agent: String, @@ -342,14 +342,14 @@ pub enum MatrixCmd { SyncAdmin, /// Promote a matrix user to homeserver admin. PromoteUser { - /// Matrix localpart of the user to promote (e.g. `argus`). + /// Matrix localpart of the user to promote (for example `argus`). name: String, }, /// Reset a matrix user's password via the admin API. /// /// Persists the new password so a later `create-user` can re-login. ResetPassword { - /// Matrix localpart of the account to reset (e.g. `argus`). + /// Matrix localpart of the account to reset (for example `argus`). name: String, }, /// Invite a matrix user to the hive Space, or a specific room with @@ -418,7 +418,7 @@ pub enum WgCmd { /// Generate this hive's WireGuard key (if absent) and print its public /// key plus the nix to enable the mesh. Init { - /// This hive's mesh address (e.g. `10.42.0.1/32`) to bake into the + /// This hive's mesh address (for example `10.42.0.1/32`) to bake into the /// printed snippet. Omit to get a placeholder you fill in. #[arg(long)] address: Option, @@ -430,11 +430,11 @@ pub enum WgCmd { /// Peer's WireGuard public key (from its `hivectl wg init`). #[arg(long)] pubkey: String, - /// Peer's mesh address (e.g. `10.42.0.2/32`). + /// Peer's mesh address (for example `10.42.0.2/32`). #[arg(long)] address: String, /// Peer's `host:port` endpoint (omit for a peer that only dials out, - /// e.g. one behind NAT — it must set an endpoint pointing back here). + /// for example one behind NAT — it must set an endpoint pointing back here). #[arg(long)] endpoint: Option, }, @@ -480,7 +480,7 @@ pub enum AgentCmd { /// Start (or leave) the agent paused: if it's currently down, the /// pause marker is written before the container boots, so it comes /// up paused instead of driving turns immediately. If it's already - /// running, this pauses it in place and does not attempt a + /// running, this pauses it in place and doesn't attempt a /// (re)start. #[arg(long)] paused: bool, @@ -525,10 +525,10 @@ pub enum AgentCmd { /// change one and keep the other, pass both. Disk is a separate /// resource with its own group — see `quota`. SetLimits { - /// systemd `CPUQuota=` value, e.g. `400%` (100% = one full core). + /// systemd `CPUQuota=` value, for example `400%` (100% = one full core). #[arg(long, conflicts_with = "reset")] cpu_quota: Option, - /// systemd `MemoryMax=` value, e.g. `8G`, `50%`, or `infinity`. + /// systemd `MemoryMax=` value, for example `8G`, `50%`, or `infinity`. #[arg(long, conflicts_with = "reset")] memory_max: Option, /// Drop all overrides — the agent returns to the hive-wide diff --git a/swarmctl/src/main.rs b/swarmctl/src/main.rs index 515dc78b..13679c7d 100644 --- a/swarmctl/src/main.rs +++ b/swarmctl/src/main.rs @@ -58,10 +58,10 @@ struct PathArgs { /// rather than whatever is on `PATH`. #[arg(long, value_name = "PATH")] authelia_bin: Option, - /// Host-side path of authelia's users database — i.e. the path inside + /// Host-side path of authelia's users database — that is the path inside /// the container, prefixed with the container's root. /// - /// This is the only user store: it is read before every change and + /// This is the only user store: it's read before every change and /// written in place, and `swarm-authelia-bridge` writes the same file. // // The `--store` flag that named a second, private JSON store is gone @@ -162,7 +162,7 @@ enum UserVerb { #[derive(Args)] struct AddArgs { - /// Login name. Conservative ASCII only — it is a YAML map key and + /// Login name. Conservative ASCII only — it's a YAML map key and /// reaches access-control rules and logs. username: String, /// Name shown in the SSO UI. Defaults to the username. @@ -184,10 +184,10 @@ struct UpdateArgs { display_name: Option, #[arg(long, value_name = "ADDRESS")] email: Option, - /// Repeatable. Adding a group the user is already in is not an error. + /// Repeatable. Adding a group the user is already in isn't an error. #[arg(long = "add-group", value_name = "GROUP")] add_groups: Vec, - /// Repeatable. Fails if the user is not in the group — a revocation + /// Repeatable. Fails if the user isn't in the group — a revocation /// that reports success without revoking is the failure nobody /// re-checks. #[arg(long = "remove-group", value_name = "GROUP")]