From b4eddf158d21c7857dd7f886aaad167a51010fc4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 10 Jul 2021 21:00:34 +0200 Subject: [PATCH] fix remaining intra-doc links --- clap_derive/src/lib.rs | 4 +- clap_generate/src/generators/mod.rs | 24 +++++------ src/build/app/mod.rs | 21 ++++++---- src/build/app/settings.rs | 64 ++++++++++++++++------------- src/build/arg/mod.rs | 35 +++++++++------- src/build/arg/settings.rs | 7 ++-- src/build/arg/value_hint.rs | 3 +- 7 files changed, 87 insertions(+), 71 deletions(-) diff --git a/clap_derive/src/lib.rs b/clap_derive/src/lib.rs index 83d0ad4e811..6ab11e00490 100644 --- a/clap_derive/src/lib.rs +++ b/clap_derive/src/lib.rs @@ -43,8 +43,8 @@ pub fn arg_enum(input: TokenStream) -> TokenStream { /// Generates the `Clap` implementation. /// -/// This is far less verbose than defining the [`App`] struct manually, -/// receiving an instance of [`ArgMatches`] from conducting parsing, and then +/// This is far less verbose than defining the `clap::App` struct manually, +/// receiving an instance of `clap::ArgMatches` from conducting parsing, and then /// implementing a conversion code to instantiate an instance of the user /// context struct. #[proc_macro_derive(Clap, attributes(clap))] diff --git a/clap_generate/src/generators/mod.rs b/clap_generate/src/generators/mod.rs index 0597d22e7df..53f14cf0d46 100644 --- a/clap_generate/src/generators/mod.rs +++ b/clap_generate/src/generators/mod.rs @@ -29,12 +29,12 @@ pub trait Generator { /// ``` fn file_name(name: &str) -> String; - /// Generates output out of [`clap::App`](super::clap::App). + /// Generates output out of [`clap::App`](App). /// /// # Examples /// - /// The following example generator displays the [`clap::App`](super::clap::App) - /// as if it is printed using [`std::println`](std::println!). + /// The following example generator displays the [`clap::App`](App) + /// as if it is printed using [`std::println`]. /// /// ``` /// use std::{io::Write, fmt::write}; @@ -68,11 +68,9 @@ pub trait Generator { subcmds } - /// Finds the subcommand [`clap::App`][clap] from the given [`clap::App`][clap] with the given path. + /// Finds the subcommand [`clap::App`] from the given [`clap::App`] with the given path. /// /// **NOTE:** `path` should not contain the root `bin_name`. - /// - /// [clap]: super::clap::App fn find_subcommand_with_path<'help, 'app>( p: &'app App<'help>, path: Vec<&str>, @@ -86,7 +84,7 @@ pub trait Generator { app } - /// Gets subcommands of [`clap::App`](super::clap::App) in the form of `("name", "bin_name")`. + /// Gets subcommands of [`clap::App`] in the form of `("name", "bin_name")`. /// /// Subcommand `rustup toolchain install` would be converted to /// `("install", "rustup toolchain install")`. @@ -115,8 +113,8 @@ pub trait Generator { subcmds } - /// Gets all the short options, their visible aliases and flags of a [`clap::App`](super::clap::App). - /// Includes `h` and `V` depending on the [`clap::AppSettings`](super::clap::AppSettings). + /// Gets all the short options, their visible aliases and flags of a [`clap::App`]. + /// Includes `h` and `V` depending on the [`clap::AppSettings`]. fn shorts_and_visible_aliases(p: &App) -> Vec { debug!("shorts: name={}", p.get_name()); @@ -140,8 +138,8 @@ pub trait Generator { .collect() } - /// Gets all the long options, their visible aliases and flags of a [`clap::App`](super::clap::App). - /// Includes `help` and `version` depending on the [`clap::AppSettings`](super::clap::AppSettings). + /// Gets all the long options, their visible aliases and flags of a [`clap::App`]. + /// Includes `help` and `version` depending on the [`clap::AppSettings`]. fn longs_and_visible_aliases(p: &App) -> Vec { debug!("longs: name={}", p.get_name()); @@ -170,8 +168,8 @@ pub trait Generator { .collect() } - /// Gets all the flags of a [`clap::App`](super::clap::App). - /// Includes `help` and `version` depending on the [`clap::AppSettings`](super::clap::AppSettings). + /// Gets all the flags of a [`clap::App`](App). + /// Includes `help` and `version` depending on the [`clap::AppSettings`]. fn flags<'help>(p: &App<'help>) -> Vec> { debug!("flags: name={}", p.get_name()); p.get_flags().cloned().collect() diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index f4e211ea5c5..195f8ce66b3 100644 --- a/src/build/app/mod.rs +++ b/src/build/app/mod.rs @@ -801,7 +801,7 @@ impl<'help> App<'help> { /// /// **NOTE:** This **only** replaces the help message for the current /// command, meaning if you are using subcommands, those help messages will - /// still be auto-generated unless you specify a [`Arg::override_help`] for + /// still be auto-generated unless you specify a [`App::override_help`] for /// them as well. /// /// # Examples @@ -826,7 +826,6 @@ impl<'help> App<'help> { /// work Do some work") /// # ; /// ``` - /// [`Arg::override_help`]: Arg::override_help() pub fn override_help>(mut self, help: S) -> Self { self.help_str = Some(help.into()); self @@ -1982,11 +1981,13 @@ impl<'help> App<'help> { /// .unwrap_or_else(|e| e.exit()); /// ``` /// [`env::args_os`]: std::env::args_os() - /// [`Error::exit`]: Error::exit() + /// [`Error::exit`]: crate::Error::exit() /// [`std::process::exit`]: std::process::exit() /// [`clap::Result`]: Result - /// [`clap::Error`]: Error - /// [`kind`]: Error + /// [`clap::Error`]: crate::Error + /// [`kind`]: crate::Error + /// [`ErrorKind::DisplayHelp`]: crate::ErrorKind::DisplayHelp + /// [`ErrorKind::DisplayVersion`]: crate::ErrorKind::DisplayVersion #[inline] pub fn try_get_matches(self) -> ClapResult { // Start the parsing @@ -2064,11 +2065,13 @@ impl<'help> App<'help> { /// ``` /// [`App::get_matches_from`]: App::get_matches_from() /// [`App::try_get_matches`]: App::try_get_matches() - /// [`Error::exit`]: Error::exit() + /// [`Error::exit`]: crate::Error::exit() /// [`std::process::exit`]: std::process::exit() - /// [`clap::Error`]: Error - /// [`Error::exit`]: Error::exit() - /// [`kind`]: Error + /// [`clap::Error`]: crate::Error + /// [`Error::exit`]: crate::Error::exit() + /// [`kind`]: crate::Error + /// [`ErrorKind::DisplayHelp`]: crate::ErrorKind::DisplayHelp + /// [`ErrorKind::DisplayVersion`]: crate::ErrorKind::DisplayVersion pub fn try_get_matches_from(mut self, itr: I) -> ClapResult where I: IntoIterator, diff --git a/src/build/app/settings.rs b/src/build/app/settings.rs index 955f482367c..f15b481a061 100644 --- a/src/build/app/settings.rs +++ b/src/build/app/settings.rs @@ -206,11 +206,11 @@ pub enum AppSettings { /// assert_eq!(m.value_of_os("arg").unwrap().as_bytes(), &[0xe9]); /// ``` /// - /// [`ArgMatches::value_of_os`]: ArgMatches::value_of_os() - /// [`ArgMatches::values_of_os`]: ArgMatches::values_of_os() - /// [`ArgMatches::value_of_lossy`]: ArgMatches::value_of_lossy() - /// [`ArgMatches::values_of_lossy`]: ArgMatches::values_of_lossy() - /// [`subcommands`]: App::subcommand() + /// [`ArgMatches::value_of_os`]: crate::ArgMatches::value_of_os() + /// [`ArgMatches::values_of_os`]: crate::ArgMatches::values_of_os() + /// [`ArgMatches::value_of_lossy`]: crate::ArgMatches::value_of_lossy() + /// [`ArgMatches::values_of_lossy`]: crate::ArgMatches::values_of_lossy() + /// [`subcommands`]: crate::App::subcommand() // TODO: Either this or StrictUtf8 AllowInvalidUtf8, @@ -236,13 +236,13 @@ pub enum AppSettings { /// assert_eq!(m.value_of("neg"), Some("-20")); /// # ; /// ``` - /// [`Arg::allow_hyphen_values`]: Arg::allow_hyphen_values() + /// [`Arg::allow_hyphen_values`]: crate::Arg::allow_hyphen_values() AllowLeadingHyphen, /// Specifies that all arguments override themselves. This is the equivalent to saying the `foo` /// arg using [`Arg::overrides_with("foo")`] for all defined arguments. /// - /// [`Arg::overrides_with("foo")`]: Arg::overrides_with() + /// [`Arg::overrides_with("foo")`]: crate::Arg::overrides_with() AllArgsOverrideSelf, /// Allows negative numbers to pass as values. This is similar to @@ -371,7 +371,7 @@ pub enum AppSettings { /// assert_eq!(m.values_of("baz").unwrap().collect::>(), &["baz1", "baz2", "baz3"]); /// ``` /// - /// [required]: Arg::required() + /// [required]: crate::Arg::required() AllowMissingPositional, /// Specifies that an unexpected positional argument, @@ -405,7 +405,10 @@ pub enum AppSettings { /// _ => {}, /// } /// ``` - /// [`subcommand`]: App::subcommand() + /// + /// [`subcommand`]: crate::App::subcommand() + /// [`ArgMatches`]: crate::ArgMatches + /// [`ErrorKind::UnknownArgument`]: crate::ErrorKind::UnknownArgument AllowExternalSubcommands, /// Specifies that use of a valid argument negates [`subcommands`] being used after. By default @@ -426,7 +429,7 @@ pub enum AppSettings { /// .setting(AppSettings::ArgsNegateSubcommands); /// ``` /// - /// [`subcommands`]: App::subcommand() + /// [`subcommands`]: crate::App::subcommand() ArgsNegateSubcommands, /// Specifies that the help text should be displayed (and then exit gracefully), @@ -445,8 +448,8 @@ pub enum AppSettings { /// .setting(AppSettings::ArgRequiredElseHelp); /// ``` /// - /// [`subcommands`]: App::subcommand() - /// [`Arg::default_value`]: Arg::default_value() + /// [`subcommands`]: crate::App::subcommand() + /// [`Arg::default_value`]: crate::Arg::default_value() ArgRequiredElseHelp, /// Instructs the parser to stop when encountering a subcommand instead of greedily consuming @@ -621,7 +624,8 @@ pub enum AppSettings { /// .setting(AppSettings::DontDelimitTrailingValues) /// .get_matches(); /// ``` - /// [`Arg::use_delimiter(false)`]: Arg::use_delimiter() + /// + /// [`Arg::use_delimiter(false)`]: crate::Arg::use_delimiter() DontDelimitTrailingValues, /// Disables `-h` and `--help` flag. @@ -658,7 +662,7 @@ pub enum AppSettings { /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` /// - /// [`subcommand`]: App::subcommand() + /// [`subcommand`]: crate::App::subcommand() DisableHelpSubcommand, /// Disables `-V` and `--version` flag. @@ -694,7 +698,8 @@ pub enum AppSettings { /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` /// - /// [`subcommands`]: App::subcommand() + /// [`subcommands`]: crate::App::subcommand() + /// [`App`]: crate::App DisableVersionForSubcommands, /// Displays the arguments and [`subcommands`] in the help message in the order that they were @@ -709,7 +714,7 @@ pub enum AppSettings { /// .get_matches(); /// ``` /// - /// [`subcommands`]: App::subcommand() + /// [`subcommands`]: crate::App::subcommand() DeriveDisplayOrder, /// Specifies to use the version of the current command for all child [`subcommands`]. @@ -729,7 +734,7 @@ pub enum AppSettings { /// // "myprog-test v1.1" /// ``` /// - /// [`subcommands`]: App::subcommand() + /// [`subcommands`]: crate::App::subcommand() GlobalVersion, /// Specifies that this [`subcommand`] should be hidden from help messages @@ -744,7 +749,7 @@ pub enum AppSettings { /// # ; /// ``` /// - /// [`subcommand`]: App::subcommand() + /// [`subcommand`]: crate::App::subcommand() Hidden, /// Tells `clap` *not* to print possible values when displaying help information. @@ -841,9 +846,9 @@ pub enum AppSettings { /// assert_eq!(m.subcommand_name(), Some("test")); /// ``` /// - /// [`subcommands`]: App::subcommand() - /// [positional/free arguments]: Arg::index() - /// [aliases]: App::alias() + /// [`subcommands`]: crate::App::subcommand() + /// [positional/free arguments]: crate::Arg::index() + /// [aliases]: crate::App::alias() InferSubcommands, /// Tries to match unknown args to partial long arguments or their [aliases]. For example, to @@ -852,6 +857,8 @@ pub enum AppSettings { /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match /// `--te` to `--test` there could not also be another argument or alias `--temp` because both /// start with `--te` + /// + /// [aliases]: crate::App::alias() InferLongArgs, /// Specifies that the parser should not assume the first argument passed is the binary name. @@ -926,8 +933,8 @@ pub enum AppSettings { /// # ; /// ``` /// - /// [`Arg::required(true)`]: Arg::required() - /// [`subcommands`]: App::subcommand() + /// [`Arg::required(true)`]: crate::Arg::required() + /// [`subcommands`]: crate::App::subcommand() SubcommandsNegateReqs, /// Specifies that the help text should be displayed (before exiting gracefully) if no @@ -948,7 +955,7 @@ pub enum AppSettings { /// .setting(AppSettings::SubcommandRequiredElseHelp); /// ``` /// - /// [`subcommands`]: App::subcommand() + /// [`subcommands`]: crate::App::subcommand() SubcommandRequiredElseHelp, /// Specifies that the help subcommand should print the [long format] help message. @@ -970,7 +977,7 @@ pub enum AppSettings { /// ) /// .get_matches(); /// ``` - /// [long format]: App::long_about + /// [long format]: crate::App::long_about UseLongFormatForHelpSubcommand, /// Specifies that any invalid UTF-8 code points should be treated as an error and fail @@ -1003,7 +1010,8 @@ pub enum AppSettings { /// assert_eq!(m.unwrap_err().kind, ErrorKind::InvalidUtf8); /// ``` /// - /// [`subcommands`]: App::subcommand() + /// [`subcommands`]: crate::App::subcommand() + /// [`ErrorKind::InvalidUtf8`]: crate::ErrorKind::InvalidUtf8 StrictUtf8, /// Allows specifying that if no [`subcommand`] is present at runtime, @@ -1024,7 +1032,7 @@ pub enum AppSettings { /// # ; /// ``` /// - /// [`subcommand`]: App::subcommand() + /// [`subcommand`]: crate::App::subcommand() SubcommandRequired, /// Specifies that the final positional argument is a "VarArg" and that `clap` should not @@ -1047,7 +1055,7 @@ pub enum AppSettings { /// let trail: Vec<&str> = m.values_of("cmd").unwrap().collect(); /// assert_eq!(trail, ["arg1", "-r", "val1"]); /// ``` - /// [`Arg::multiple_values(true)`]: Arg::multiple_values() + /// [`Arg::multiple_values(true)`]: crate::Arg::multiple_values() TrailingVarArg, /// Groups flags and options together, presenting a more unified help message diff --git a/src/build/arg/mod.rs b/src/build/arg/mod.rs index d3e48a1f88d..281fde419b3 100644 --- a/src/build/arg/mod.rs +++ b/src/build/arg/mod.rs @@ -1136,7 +1136,7 @@ impl<'help> Arg<'help> { /// assert!(m.is_present("flag")); /// assert_eq!(m.occurrences_of("flag"), 1); /// ``` - /// Making an arg [`Multiple*``] and override itself is essentially meaningless. Therefore + /// Making an arg [`Multiple*`] and override itself is essentially meaningless. Therefore /// clap ignores an override of self if it's a flag and it already accepts multiple occurrences. /// /// ``` @@ -1160,7 +1160,7 @@ impl<'help> Arg<'help> { /// assert_eq!(m.value_of("opt"), Some("other")); /// ``` /// - /// Just like flags, options with one of the [`Multiple*``] set, will ignore the "override self" + /// Just like flags, options with one of the [`Multiple*`] set, will ignore the "override self" /// setting. /// /// ``` @@ -1188,7 +1188,7 @@ impl<'help> Arg<'help> { /// assert_eq!(m.occurrences_of("opt"), 1); /// assert_eq!(m.values_of("opt").unwrap().collect::>(), &["one,two"]); /// ``` - /// [`Multiple*`]: ArgSettings::MultipleValues + /// [`Multiple*`]: crate::ArgSettings::MultipleValues /// [`UseValueDelimiter`]: ArgSettings::UseValueDelimiter pub fn overrides_with(mut self, arg_id: T) -> Self { self.overrides.push(arg_id.into()); @@ -1787,6 +1787,7 @@ impl<'help> Arg<'help> { /// [`Arg::long`]: Arg::long() /// [`Arg::multiple_values(true)`]: Arg::multiple_values() /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html + /// [`App`]: crate::App #[inline] pub fn index(mut self, idx: usize) -> Self { self.index = Some(idx); @@ -1985,6 +1986,8 @@ impl<'help> Arg<'help> { /// ]); /// assert!(m.is_present("mode")); /// ``` + /// + /// [`ArgGroup`]: crate::ArgGroup pub fn group(mut self, group_id: T) -> Self { self.groups.push(group_id.into()); self @@ -2020,6 +2023,8 @@ impl<'help> Arg<'help> { /// assert!(m.is_present("mode")); /// assert!(m.is_present("verbosity")); /// ``` + /// + /// [`ArgGroup`]: crate::ArgGroup pub fn groups(mut self, group_ids: &[T]) -> Self { self.groups.extend(group_ids.iter().map(Id::from)); self @@ -2613,10 +2618,10 @@ impl<'help> Arg<'help> { /// assert!(m.is_present("opt")); /// assert_eq!(m.occurrences_of("opt"), 1); /// ``` - /// [`ArgMatches::occurrences_of`]: ArgMatches::occurrences_of() - /// [`ArgMatches::value_of`]: ArgMatches::value_of() + /// [`ArgMatches::occurrences_of`]: crate::ArgMatches::occurrences_of() + /// [`ArgMatches::value_of`]: crate::ArgMatches::value_of() /// [`Arg::takes_value(true)`]: Arg::takes_value() - /// [`ArgMatches::is_present`]: ArgMatches::is_present() + /// [`ArgMatches::is_present`]: crate::ArgMatches::is_present() /// [`Arg::default_value_if`]: Arg::default_value_if() #[inline] pub fn default_value(self, val: &'help str) -> Self { @@ -3130,7 +3135,7 @@ impl<'help> Arg<'help> { /// assert_eq!(m.values_of("flag").unwrap().collect::>(), vec!["env1", "env2"]); /// ``` /// [`ArgMatches::occurrences_of`]: ArgMatches::occurrences_of() - /// [`ArgMatches::value_of`]: ArgMatches::value_of() + /// [`ArgMatches::value_of`]: crate::ArgMatches::value_of() /// [`ArgMatches::is_present`]: ArgMatches::is_present() /// [`Arg::takes_value(true)`]: Arg::takes_value() /// [`Arg::use_delimiter(true)`]: Arg::use_delimiter() @@ -3219,17 +3224,17 @@ impl<'help> Arg<'help> { /// **NOTE:** This will change the usage string to look like `$ prog [FLAGS] [-- ]` if /// `ARG` is marked as `.last(true)`. /// - /// **NOTE:** This setting will imply [`AppSettings::DontCollapseArgsInUsage`] because failing + /// **NOTE:** This setting will imply [`crate::AppSettings::DontCollapseArgsInUsage`] because failing /// to set this can make the usage string very confusing. /// /// **NOTE**: This setting only applies to positional arguments, and has no affect on FLAGS / /// OPTIONS /// - /// **NOTE:** Setting this requires [`ArgSettings::TakesValue`] + /// **NOTE:** Setting this requires [`crate::ArgSettings::TakesValue`] /// /// **CAUTION:** Using this setting *and* having child subcommands is not - /// recommended with the exception of *also* using [`AppSettings::ArgsNegateSubcommands`] - /// (or [`AppSettings::SubcommandsNegateReqs`] if the argument marked `Last` is also + /// recommended with the exception of *also* using [`crate::AppSettings::ArgsNegateSubcommands`] + /// (or [`crate::AppSettings::SubcommandsNegateReqs`] if the argument marked `Last` is also /// marked [`ArgSettings::Required`]) /// /// # Examples @@ -3282,7 +3287,7 @@ impl<'help> Arg<'help> { /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` /// [index]: Arg::index() - /// [`UnknownArgument`]: ErrorKind::UnknownArgument + /// [`UnknownArgument`]: crate::ErrorKind::UnknownArgument #[inline] pub fn last(self, l: bool) -> Self { if l { @@ -3987,7 +3992,7 @@ impl<'help> Arg<'help> { /// This can also be helpful for arguments with very long flag names, or many/long value names. /// /// **NOTE:** To apply this setting to all arguments consider using - /// [`AppSettings::NextLineHelp`] + /// [`crate::AppSettings::NextLineHelp`] /// /// # Examples /// @@ -4260,7 +4265,7 @@ impl<'help> Arg<'help> { /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` /// - /// [`subcommands`]: App::subcommand() + /// [`subcommands`]: crate::App::subcommand() /// [`Arg::number_of_values(1)`]: Arg::number_of_values() /// [`MultipleOccurrences`]: ArgSettings::MultipleOccurrences /// [`MultipleValues`]: ArgSettings::MultipleValues @@ -4346,7 +4351,7 @@ impl<'help> Arg<'help> { /// ``` /// /// Will result in everything after `--` to be considered one raw argument. This behavior - /// may not be exactly what you are expecting and using [`AppSettings::TrailingVarArg`] + /// may not be exactly what you are expecting and using [`crate::AppSettings::TrailingVarArg`] /// may be more appropriate. /// /// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] [`Arg::multiple_values(true)`], diff --git a/src/build/arg/settings.rs b/src/build/arg/settings.rs index 7254c0b6c8b..7143aa51aff 100644 --- a/src/build/arg/settings.rs +++ b/src/build/arg/settings.rs @@ -68,9 +68,10 @@ impl Default for ArgFlags { /// methods [`Arg::setting`], [`Arg::unset_setting`], and [`Arg::is_set`]. This is what the /// [`Arg`] methods which accept a `bool` use internally. /// -/// [`Arg::setting`]: Arg::setting() -/// [`Arg::unset_setting`]: Arg::unset_setting() -/// [`Arg::is_set`]: Arg::is_set() +/// [`Arg`]: crate::Arg +/// [`Arg::setting`]: crate::Arg::setting() +/// [`Arg::unset_setting`]: crate::Arg::unset_setting() +/// [`Arg::is_set`]: crate::Arg::is_set() #[derive(Debug, PartialEq, Copy, Clone)] pub enum ArgSettings { /// Specifies that an arg must be used diff --git a/src/build/arg/value_hint.rs b/src/build/arg/value_hint.rs index 34886a9926f..3974529a7a9 100644 --- a/src/build/arg/value_hint.rs +++ b/src/build/arg/value_hint.rs @@ -49,7 +49,8 @@ pub enum ValueHint { /// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to /// parse the `-la` argument itself. /// - /// [`.multiple_values(true)`]: Arg::multiple_values() + /// [`AppSettings::TrailingVarArg`]: crate::AppSettings::TrailingVarArg + /// [`.multiple_values(true)`]: crate::Arg::multiple_values() CommandWithArguments, /// Name of a local operating system user. Username,