From 4fce7da1a80d74b708910e65190dd960b6506172 Mon Sep 17 00:00:00 2001 From: alexpasmantier Date: Mon, 17 Mar 2025 22:12:41 +0100 Subject: [PATCH] docs(cli): improve cli documentation --- Cargo.toml | 2 +- television/cli.rs | 90 ++++++++++++++++++++++++++++++++++------------- 2 files changed, 67 insertions(+), 25 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index e02879c..34c7223 100644 --- a/Cargo.toml +++ b/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 "] repository = "https://github.com/alexpasmantier/television" diff --git a/television/cli.rs b/television/cli.rs index 0e8cc3a..6ab7a1d 100644 --- a/television/cli.rs +++ b/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) - #[arg(short, long, value_name = "STRING")] + /// A preview command to use with the stdin channel. + /// + /// 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, - /// Disable the preview pane - #[arg(long, default_value = "false")] + /// Disable the preview panel entirely on startup. + #[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 - /// (defaults to " ") - #[arg(long, value_name = "STRING", default_value = " ", value_parser = delimiter_parser)] + /// The delimiter used to extract fields from the entry to provide to the + /// preview command. + /// + /// 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 - #[arg(short, long, value_name = "FLOAT")] + /// The application's tick rate. + /// + /// 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, - /// [DEPRECATED] Frame rate, i.e. number of frames per second - #[arg(short, long, value_name = "FLOAT")] + /// [DEPRECATED] Frame rate, i.e. number of frames to render per second. + /// + /// 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, - /// Passthrough keybindings (comma separated, e.g. "q,ctrl-w,ctrl-t") These keybindings will - /// trigger selection of the current entry and be passed through to stdout along with the entry - /// to be handled by the parent process. - #[arg(long, value_name = "STRING")] + /// Passthrough keybindings (comma separated, e.g. "q,ctrl-w,ctrl-t") + /// + /// These keybindings will trigger selection of the current entry and be + /// 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, - /// Input text to pass to the channel to prefill the prompt - #[arg(short, long, value_name = "STRING")] + /// Input text to pass to the channel to prefill the prompt. + /// + /// 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, - /// The working directory to start in - #[arg(value_name = "PATH", index = 2)] + /// The working directory to start the application in. + /// + /// 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, - /// Try to guess the channel from the provided input prompt - #[arg(long, value_name = "STRING")] + /// Try to guess the channel from the provided input prompt. + /// + /// 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, #[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")]