Normalize user-facing --help text for tone/format consistency

Follow-up to the previous comment pass, which covered source comments -
this one is specifically the doc comments that render as --help output:

- Dropped "Deep-dive" (casual/jargon) from status's description in favor
  of the imperative-verb pattern every other command description uses
  (Save/Start/Stop/Update/List/Delete/Generate).
- Replaced the "SIGTERM + wait" shorthand in close --force's help with a
  plain sentence - "+" as an ad-hoc conjunction doesn't belong in
  user-facing text.
- Unified all positional NAME descriptions to the same "Name of the
  profile to <verb>" shape (add's was "Name for the new profile",
  breaking the pattern); open's picked up the same parenthetical-clarifier
  convention already used elsewhere ("(ignored with --all)", matching
  "(doesn't open it)", "(SOCKS proxy)").
- Trimmed the redundant "SSH" prefix from --via's description (the whole
  tool is SSH-specific, so it added nothing); kept it on --port's, where
  it disambiguates the SSH connection port from the forward's own port
  numbers.
- Fixed the Cli struct's doc comment to match what --command(about)
  actually renders (Cargo.toml's description, not the doc comment
  verbatim) - it carried a stale "porthole - " prefix that never showed.
This commit is contained in:
2026-08-13 17:21:58 +02:00
parent 4170d51cf5
commit e36360e18c

View File

@@ -1,7 +1,7 @@
use clap::{Args, Parser, Subcommand};
use clap_complete::Shell;
/// porthole - create and manage named SSH port forwards.
/// Create and manage named SSH port forwards.
#[derive(Parser)]
#[command(name = "porthole", version, about)]
pub struct Cli {
@@ -26,7 +26,7 @@ pub enum Commands {
/// Update a saved profile.
Edit(EditArgs),
/// Deep-dive health for one forward.
/// Show detailed status for one forward.
Status(StatusArgs),
/// List all saved profiles with live status.
@@ -66,7 +66,7 @@ pub struct MappingArgs {
#[arg(short, long, value_name = "[BIND:]PORT")]
pub dynamic: Option<String>,
/// SSH hop chain: jump hosts plus the final connection target.
/// Jump-host chain, ending at the connection target.
#[arg(long, value_name = "[USER@]HOST[:PORT]", value_delimiter = ',')]
pub via: Vec<String>,
@@ -101,7 +101,7 @@ pub struct MappingArgs {
#[derive(Args)]
pub struct AddArgs {
/// Name for the new profile.
/// Name of the new profile.
pub name: String,
#[command(flatten)]
@@ -119,7 +119,7 @@ pub struct EditArgs {
#[derive(Args)]
pub struct OpenArgs {
/// Name of the profile to open. Ignored (and optional) with --all.
/// Name of the profile to open (ignored with --all).
pub name: Option<String>,
/// Run attached in the current shell instead of detaching.
@@ -140,7 +140,7 @@ pub struct CloseArgs {
/// Name of the profile to close.
pub name: String,
/// SIGKILL immediately instead of graceful SIGTERM + wait.
/// Send SIGKILL immediately instead of SIGTERM with a graceful wait.
#[arg(long)]
pub force: bool,
}