docs(cli): improve cli documentation

Cargo.toml

@@ -2,7 +2,7 @@
 name = "television"
 version = "0.10.9"
 edition = "2021"
-description = "The revolution will be televised."
+description = "A cross-platform, fast and extensible general purpose fuzzy finder TUI."
 license = "MIT"
 authors = ["Alexandre Pasmantier <alex.pasmant@gmail.com>"]
 repository = "https://github.com/alexpasmantier/television"

television/cli.rs

@@ -15,49 +15,91 @@ use crate::{
 };
 
 #[derive(Parser, Debug)]
-#[command(author, version = version(), about)]
+#[command(version, about, long_about = None)]
 pub struct Cli {
     /// Which channel shall we watch?
-    #[arg(value_enum, default_value = "files", index = 1)]
+    ///
+    /// A list of the available channels can be displayed using the
+    /// `list-channels` command. The channel can also be changed from within
+    /// the application.
+    #[arg(
+        value_enum,
+        default_value = "files",
+        index = 1,
+        verbatim_doc_comment
+    )]
     pub channel: String,
 
-    /// Use a custom preview command (currently only supported by the stdin channel)
+    /// A preview command to use with the stdin channel.
-    #[arg(short, long, value_name = "STRING")]
+    ///
+    /// If provided, the preview command will be executed and formatted using
+    /// the entry.
+    /// Example: "bat -n --color=always {}" (where {} will be replaced with
+    /// the entry)
+    ///
+    /// Parts of the entry can be extracted positionally using the `delimiter`
+    /// option.
+    /// Example: "echo {0} {1}" will split the entry by the delimiter and pass
+    /// the first two fields to the command.
+    #[arg(short, long, value_name = "STRING", verbatim_doc_comment)]
     pub preview: Option<String>,
 
-    /// Disable the preview pane
+    /// Disable the preview panel entirely on startup.
-    #[arg(long, default_value = "false")]
+    #[arg(long, default_value = "false", verbatim_doc_comment)]
     pub no_preview: bool,
 
-    /// The delimiter used to extract fields from the entry to provide to the preview command
+    /// The delimiter used to extract fields from the entry to provide to the
-    /// (defaults to " ")
+    /// preview command.
-    #[arg(long, value_name = "STRING", default_value = " ", value_parser = delimiter_parser)]
+    ///
+    /// See the `preview` option for more information.
+    #[arg(long, value_name = "STRING", default_value = " ", value_parser = delimiter_parser, verbatim_doc_comment)]
     pub delimiter: String,
 
-    /// Tick rate, i.e. number of ticks per second
+    /// The application's tick rate.
-    #[arg(short, long, value_name = "FLOAT")]
+    ///
+    /// The tick rate is the number of times the application will update per
+    /// second. This can be used to control responsiveness and CPU usage on
+    /// very slow machines or very fast ones but the default should be a good
+    /// compromise for most users.
+    #[arg(short, long, value_name = "FLOAT", verbatim_doc_comment)]
     pub tick_rate: Option<f64>,
 
-    /// [DEPRECATED] Frame rate, i.e. number of frames per second
+    /// [DEPRECATED] Frame rate, i.e. number of frames to render per second.
-    #[arg(short, long, value_name = "FLOAT")]
+    ///
+    /// This option is deprecated and will be removed in a future release.
+    #[arg(short, long, value_name = "FLOAT", verbatim_doc_comment)]
     pub frame_rate: Option<f64>,
 
-    /// Passthrough keybindings (comma separated, e.g. "q,ctrl-w,ctrl-t") These keybindings will
+    /// Passthrough keybindings (comma separated, e.g. "q,ctrl-w,ctrl-t")
-    /// trigger selection of the current entry and be passed through to stdout along with the entry
+    ///
-    /// to be handled by the parent process.
+    /// These keybindings will trigger selection of the current entry and be
-    #[arg(long, value_name = "STRING")]
+    /// passed through to stdout along with the entry to be handled by the
+    /// parent process.
+    #[arg(long, value_name = "STRING", verbatim_doc_comment)]
     pub passthrough_keybindings: Option<String>,
 
-    /// Input text to pass to the channel to prefill the prompt
+    /// Input text to pass to the channel to prefill the prompt.
-    #[arg(short, long, value_name = "STRING")]
+    ///
+    /// This can be used to provide a default value for the prompt upon
+    /// startup.
+    #[arg(short, long, value_name = "STRING", verbatim_doc_comment)]
     pub input: Option<String>,
 
-    /// The working directory to start in
+    /// The working directory to start the application in.
-    #[arg(value_name = "PATH", index = 2)]
+    ///
+    /// This can be used to specify a different working directory for the
+    /// application to start in. This is useful when the application is
+    /// started from a different directory than the one the user wants to
+    /// interact with.
+    #[arg(value_name = "PATH", index = 2, verbatim_doc_comment)]
     pub working_directory: Option<String>,
 
-    /// Try to guess the channel from the provided input prompt
+    /// Try to guess the channel from the provided input prompt.
-    #[arg(long, value_name = "STRING")]
+    ///
+    /// This can be used to automatically select a channel based on the input
+    /// prompt by using the `shell_integration` mapping in the configuration
+    /// file.
+    #[arg(long, value_name = "STRING", verbatim_doc_comment)]
     pub autocomplete_prompt: Option<String>,
 
     #[command(subcommand)]
@@ -66,7 +108,7 @@ pub struct Cli {
 
 #[derive(Subcommand, Debug, PartialEq, Clone)]
 pub enum Command {
-    /// Lists available channels
+    /// Lists the available channels.
     ListChannels,
     /// Initializes shell completion ("tv init zsh")
     #[clap(name = "init")]