Merge pull request #5644 from epage/complete

doc(complete): More polish

clap_builder/src/builder/value_hint.rs

@@ -8,19 +8,19 @@ use std::str::FromStr;
 ///
 /// Overview of which hints are supported by which shell:
 ///
-/// | Hint                   | zsh | fish[^1]|
-/// | ---------------------- | --- | ------- |
-/// | `AnyPath`              | Yes | Yes     |
-/// | `FilePath`             | Yes | Yes     |
-/// | `DirPath`              | Yes | Yes     |
-/// | `ExecutablePath`       | Yes | Partial |
-/// | `CommandName`          | Yes | Yes     |
-/// | `CommandString`        | Yes | Partial |
-/// | `CommandWithArguments` | Yes |         |
-/// | `Username`             | Yes | Yes     |
-/// | `Hostname`             | Yes | Yes     |
-/// | `Url`                  | Yes |         |
-/// | `EmailAddress`         | Yes |         |
+/// | Hint                   | zsh | fish[^1] | dynamic |
+/// | ---------------------- | --- | ---------|---------|
+/// | `AnyPath`              | Yes | Yes      | Yes     |
+/// | `FilePath`             | Yes | Yes      | Yes     |
+/// | `DirPath`              | Yes | Yes      | Yes     |
+/// | `ExecutablePath`       | Yes | Partial  | Yes     |
+/// | `CommandName`          | Yes | Yes      | No      |
+/// | `CommandString`        | Yes | Partial  | No      |
+/// | `CommandWithArguments` | Yes |          | No      |
+/// | `Username`             | Yes | Yes      | No      |
+/// | `Hostname`             | Yes | Yes      | No      |
+/// | `Url`                  | Yes |          | No      |
+/// | `EmailAddress`         | Yes |          | No      |
 ///
 /// [^1]: fish completions currently only support named arguments (e.g. -o or --opt), not
 ///       positional arguments.

clap_complete/examples/dynamic.rs

@@ -16,15 +16,13 @@ fn command() -> clap::Command {
                 .value_parser(["json", "yaml", "toml"]),
         )
         .args_conflicts_with_subcommands(true);
-    clap_complete::dynamic::shells::CompleteCommand::augment_subcommands(cmd)
+    clap_complete::dynamic::CompleteCommand::augment_subcommands(cmd)
 }
 
 fn main() {
     let cmd = command();
     let matches = cmd.get_matches();
-    if let Ok(completions) =
-        clap_complete::dynamic::shells::CompleteCommand::from_arg_matches(&matches)
-    {
+    if let Ok(completions) = clap_complete::dynamic::CompleteCommand::from_arg_matches(&matches) {
         completions.complete(&mut command());
     } else {
         println!("{matches:#?}");

clap_complete/examples/exhaustive.rs

@@ -13,9 +13,7 @@ fn main() {
     }
 
     #[cfg(feature = "unstable-dynamic")]
-    if let Ok(completions) =
-        clap_complete::dynamic::shells::CompleteCommand::from_arg_matches(&matches)
-    {
+    if let Ok(completions) = clap_complete::dynamic::CompleteCommand::from_arg_matches(&matches) {
         completions.complete(&mut cli());
         return;
     };
@@ -198,6 +196,6 @@ fn cli() -> clap::Command {
             ]),
         ]);
     #[cfg(feature = "unstable-dynamic")]
-    let cli = clap_complete::dynamic::shells::CompleteCommand::augment_subcommands(cli);
+    let cli = clap_complete::dynamic::CompleteCommand::augment_subcommands(cli);
     cli
 }

clap_complete/src/dynamic/mod.rs

@@ -1,6 +1,11 @@
 //! Complete commands within shells
 //!
-//! For quick-start, see [`shells::CompleteCommand`]
+//! For quick-start, see [`CompleteCommand`]
+//!
+//! To customize completions, see
+//! - [`ValueHint`][crate::ValueHint]
+//! - [`ValueEnum`][clap::ValueEnum]
+//! - [`ArgValueCompleter`]
 
 mod candidate;
 mod complete;
@@ -12,3 +17,7 @@ pub use candidate::CompletionCandidate;
 pub use complete::complete;
 pub use custom::ArgValueCompleter;
 pub use custom::CustomCompleter;
+
+// These live in `shells` because they are tightly coupled with the `ShellCompleter`s
+pub use shells::CompleteArgs;
+pub use shells::CompleteCommand;

clap_complete/src/dynamic/shells/mod.rs

@@ -30,7 +30,7 @@ use std::io::Write as _;
 /// ```no_run
 /// // src/main.rs
 /// use clap::{CommandFactory, FromArgMatches, Parser, Subcommand};
-/// use clap_complete::dynamic::shells::CompleteCommand;
+/// use clap_complete::dynamic::CompleteCommand;
 ///
 /// #[derive(Parser, Debug)]
 /// #[clap(name = "dynamic", about = "A dynamic command line tool")]
@@ -127,7 +127,7 @@ impl CompleteCommand {
 /// ```no_run
 /// // src/main.rs
 /// use clap::{CommandFactory, FromArgMatches, Parser, Subcommand};
-/// use clap_complete::dynamic::shells::CompleteArgs;
+/// use clap_complete::dynamic::CompleteArgs;
 ///
 /// #[derive(Parser, Debug)]
 /// #[clap(name = "dynamic", about = "A dynamic command line tool")]