From e36360e18c6e545eb5a46aef638430acdec44a94 Mon Sep 17 00:00:00 2001
From: Overlord <overlordontwitch@gmail.com>
Date: Thu, 13 Aug 2026 17:21:58 +0200
Subject: [PATCH] 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.
---
 src/cli.rs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 1e2ef9a..73870bc 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -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,
 }