Merge pull request #4309 from epage/docs

docs: Fix a few items

CHANGELOG.md

@@ -272,6 +272,7 @@ Easier to catch changes:
 - Removed `PartialEq` and `Eq` from `Command` so we could change external subcommands to use a `ValueParser` (#3990)
 - Various `Arg`, `Command`, and `ArgGroup` calls were switched from accepting `&[]` to `[]` via `IntoIterator` to be more flexible (#4072)
 - `Arg::short_aliases` and other builder functions that took `&[]` need the `&` dropped (#4081)
+- `ErrorKind` and `Result` moved into the `error` module
 - `ErrorKind::EmptyValue` replaced with `ErrorKind::InvalidValue` to remove an unnecessary special case (#3676, #3968)
 - `ErrorKind::UnrecognizedSubcommand` replaced with `ErrorKind::InvalidSubcommand` to remove an unnecessary special case (#3676)
 - Changed the default type of `allow_external_subcommands` from `String` to `OsString` as that is less likely to cause bugs in user applications (#3990)

src/builder/arg.rs

@@ -466,7 +466,6 @@ impl Arg {
     /// [`Arg::short`]: Arg::short()
     /// [`Arg::long`]: Arg::long()
     /// [`Arg::num_args(true)`]: Arg::num_args()
-    /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
     /// [`Command`]: crate::Command
     #[inline]
     #[must_use]

src/builder/command.rs

@@ -946,9 +946,6 @@ impl Command {
 
     /// Try not to fail on parse errors, like missing option values.
     ///
-    /// **Note:** Make sure you apply it as `global_setting` if you want this setting
-    /// to be propagated to subcommands and sub-subcommands!
-    ///
     /// **NOTE:** This choice is propagated to all child subcommands.
     ///
     /// # Examples
@@ -1132,9 +1129,6 @@ impl Command {
     ///
     /// Defaults to `false`; subcommands have independent version strings from their parents.
     ///
-    /// **Note:** Make sure you apply it as `global_setting` if you want this setting
-    /// to be propagated to subcommands and sub-subcommands!
-    ///
     /// **NOTE:** This choice is propagated to all child subcommands.
     ///
     /// # Examples
@@ -1457,6 +1451,9 @@ impl Command {
     /// automatically set your application's author(s) to the same thing as your
     /// crate at compile time.
     ///
+    /// **NOTE:** A custom [`help_template`][Command::help_template] is needed for author to show
+    /// up.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -1465,7 +1462,6 @@ impl Command {
     ///      .author("Me, me@mymain.com")
     /// # ;
     /// ```
-    /// [`crate_authors!`]: ./macro.crate_authors!.html
     #[must_use]
     pub fn author(mut self, author: impl IntoResettable<Str>) -> Self {
         self.author = author.into_resettable().into_option();
@@ -1620,7 +1616,6 @@ impl Command {
     ///     .version("v0.1.24")
     /// # ;
     /// ```
-    /// [`crate_version!`]: ./macro.crate_version!.html
     #[must_use]
     pub fn version(mut self, ver: impl IntoResettable<Str>) -> Self {
         self.version = ver.into_resettable().into_option();
@@ -1648,7 +1643,6 @@ impl Command {
     ///  binary: myprog")
     /// # ;
     /// ```
-    /// [`crate_version!`]: ./macro.crate_version!.html
     #[must_use]
     pub fn long_version(mut self, ver: impl IntoResettable<Str>) -> Self {
         self.long_version = ver.into_resettable().into_option();
@@ -1767,13 +1761,31 @@ impl Command {
     ///
     /// # Examples
     ///
+    /// For a very brief help:
+    ///
     /// ```no_run
     /// # use clap::Command;
     /// Command::new("myprog")
     ///     .version("1.0")
     ///     .help_template("{bin} ({version}) - {usage}")
     /// # ;
     /// ```
+    ///
+    /// For showing more application context:
+    ///
+    /// ```no_run
+    /// # use clap::Command;
+    /// Command::new("myprog")
+    ///     .version("1.0")
+    ///     .help_template("\
+    /// {before-help}{name} {version}
+    /// {author-with-newline}{about-with-newline}
+    /// {usage-heading} {usage}
+    ///
+    /// {all-args}{after-help}
+    /// ")
+    /// # ;
+    /// ```
     /// [`Command::about`]: Command::about()
     /// [`Command::long_about`]: Command::long_about()
     /// [`Command::after_help`]: Command::after_help()
@@ -2844,9 +2856,6 @@ impl Command {
     ///             values   subcommand
     /// ```
     ///
-    /// **Note:** Make sure you apply it as `global_setting` if you want this setting
-    /// to be propagated to subcommands and sub-subcommands!
-    ///
     /// # Examples
     ///
     /// ```rust

src/macros.rs

@@ -533,7 +533,7 @@ macro_rules! arg_impl {
 /// assert_eq!(*m.get_one::<u8>("debug").unwrap(), 0);
 /// assert_eq!(m.get_one::<String>("input"), None);
 /// ```
-/// [`Arg`]: ./struct.Arg.html
+/// [`Arg`]: crate::Arg
 #[macro_export]
 macro_rules! arg {
     ( $name:ident: $($tail:tt)+ ) => {