docs: Add document comments how to source dynamic completions

clap_complete/src/dynamic/shells/mod.rs

@@ -16,6 +16,86 @@ use crate::dynamic::Completer as _;
 /// A subcommand definition to `flatten` into your CLI
 ///
 /// This provides a one-stop solution for integrating completions into your CLI
+///
+/// # Examples
+///
+/// The following example shows how to integrate completions into your CLI and generate completions.
+///
+/// First, we should build an application. It helps if we separate out our `Command` definition into a separate file.
+///
+/// ```
+/// // src/command.rs
+/// use clap::FromArgMatches;
+/// use clap::Subcommand;
+///
+/// pub fn command() -> clap::Command {
+/// 	let cmd = clap::Command::new("dynamic")
+/// 	.arg(
+/// 		clap::Arg::new("input")
+/// 		.long("input")
+/// 		.short('i')
+/// 		.value_hint(clap::ValueHint::FilePath),
+/// 	)
+/// 	.arg(
+/// 		clap::Arg::new("format")
+/// 		.long("format")
+/// 		.short('F')
+/// 		.value_parser(["json", "yaml", "toml"]),
+/// 	)
+/// 	.args_conflicts_with_subcommands(true);
+///
+/// 	cmd
+/// }
+/// ```
+///
+/// In our regular code, we can simply call this `command()` function to get the `Command`, then call
+/// `clap_complete::dynamic::shells::CompleteCommand::augment_subcommands` to add the `complete` subcommand.
+/// Finally, we call `get_matches()`, or any of the other normal methods directly after. For example:
+///
+/// ```no_run
+/// // src/main.rs
+/// use clap::FromArgMatches;
+/// use clap::Subcommand;
+///
+/// pub fn command() -> clap::Command {
+/// 	let cmd = clap::Command::new("dynamic")
+/// 	.arg(
+/// 		clap::Arg::new("input")
+/// 		.long("input")
+/// 		.short('i')
+/// 		.value_hint(clap::ValueHint::FilePath),
+/// 	)
+/// 	.arg(
+/// 		clap::Arg::new("format")
+/// 		.long("format")
+/// 		.short('F')
+/// 		.value_parser(["json", "yaml", "toml"]),
+/// 	)
+/// 	.args_conflicts_with_subcommands(true);
+///
+/// 	cmd
+/// }
+///
+/// fn main() {
+/// 	let cmd = command();
+/// 	let cmd = clap_complete::dynamic::shells::CompleteCommand::augment_subcommands(cmd);
+/// 	let matches = cmd.get_matches();
+/// 	if let Ok(completions) =
+/// 		clap_complete::dynamic::shells::CompleteCommand::from_arg_matches(&matches)
+/// 	{
+/// 		completions.complete(&mut command());
+/// 	}
+///
+/// 	// normal logic continues...
+/// }
+///```
+///
+/// Usage for `complete` subcommand:
+///
+/// Seeing [Shell] for available shell names
+///
+/// Seeing [CompleteArgs] how to source the completion script in a file or stdout:
+///
 #[derive(clap::Subcommand)]
 #[allow(missing_docs)]
 #[derive(Clone, Debug)]
@@ -27,6 +107,70 @@ pub enum CompleteCommand {
 }
 
 /// Generally used via [`CompleteCommand`]
+///
+/// This is the arguments for the `complete` subcommand.
+///
+/// **NOTE**: We should replace the `completion.bash` to filename we wanted, also `completion.fish`, `completion.zsh`, `completion.ps1`, `completion.elv`.
+///
+/// To generate shell completion scripts, we can use the `complete` subcommand as follows:
+///
+/// - Bash
+/// 	- `your_program complete --shell bash --register /path/to/completion.bash`
+/// 	- `your_program complete --shell bash --register -`
+/// - Fish:
+/// 	- `your_program complete --shell fish --register /path/to/completion.fish`
+/// 	- `your_program complete --shell fish --register -`
+/// - Zsh:
+/// 	- `your_program complete --shell zsh --register /path/to/completion.zsh`
+/// 	- `your_program complete --shell zsh --register -`
+/// - PowerShell:
+/// 	- `your_program complete --shell powershell --register /path/to/completion.ps1`
+/// 	- `your_program complete --shell powershell --register -`
+/// - Elvish:
+/// 	- `your_program complete --shell elvish --register /path/to/completion.elv`
+/// 	- `your_program complete --shell elvish --register -`
+///
+/// **Before we source the completion script, we need to add your program to the PATH. And then
+/// we can source the completion script. Different shells have different ways to source the script.**
+///
+/// ### How to source the generated completions as a file
+/// - Bash
+/// 	- `source /path/to/completion.bash`
+/// - Fish
+/// 	- `source /path/to/completion.fish`
+/// - Zsh
+/// 	- `source /path/to/completion.zsh`
+/// - PowerShell
+/// 	- `. /path/to/completion.ps1`
+/// - Elvish
+/// 	- `./path/to/completion.elv`
+///
+/// ### How to source the generated completions when printed to stdout
+/// - Bash
+/// 	- `your_program complete --shell bash --register - > /path/to/completion.bash && source /path/to/completion.bash`
+/// - Fish
+/// 	- `your_program complete --shell fish --register - > /path/to/completion.fish && source /path/to/completion.fish`
+/// - Zsh
+/// 	- `your_program complete --shell zsh --register - > /path/to/completion.zsh && source /path/to/completion.zsh`
+/// - PowerShell
+/// 	- `your_program complete --shell powershell --register - > /path/to/completion.ps1 && . /path/to/completion.ps1`
+/// - Elvish
+/// 	- `your_program complete --shell elvish --register - > /path/to/completion.elv && ./path/to/completion.elv`
+///
+/// ### How to add the above to your shell configuration file
+/// - Bash
+/// 	- `echo 'source /path/to/completion.bash' >> ~/.bashrc`
+/// - Fish
+/// 	- `echo 'source /path/to/completion.fish' >> ~/.config/fish/config.fish`
+/// 	- `cp /path/to/completion.fish ~/.config/fish/completions/your_program.fish`
+/// - Zsh
+/// 	- `echo 'source /path/to/completion.zsh' >> ~/.zshrc`
+/// - PowerShell
+/// 	- `echo '. /path/to/completion.ps1' >> $PROFILE`
+/// - Elvish
+/// 	- `echo './path/to/completion.elv' >> ~/.elvish/rc.elv`
+///
+
 #[derive(clap::Args)]
 #[command(arg_required_else_help = true)]
 #[command(group = clap::ArgGroup::new("complete").multiple(true).conflicts_with("register"))]