docs: inter-links all types and pages

All doc pages should now be inter-linked between other doc pages and Rust documentation. Closes #505
2024-12-14 06:42:33 +00:00 · 2016-05-14 16:25:00 -04:00 · 2016-05-14 16:25:00 -04:00 · 3312893dda
commit 3312893dda
parent d392fd0edc
11 changed files with 613 additions and 349 deletions
--- a/src/app/help.rs
+++ b/src/app/help.rs
@ -73,9 +73,9 @@ macro_rules! color {
    };
 }
-/// CLAP Help Writer.
+/// `clap` Help Writer.
 ///
-/// Wraps a writer stream providing different methods to generate help for CLAP objects.
+/// Wraps a writer stream providing different methods to generate help for `clap` objects.
 pub struct Help<'a> {
    writer: &'a mut Write,
    next_line_help: bool,
@ -86,7 +86,7 @@ pub struct Help<'a> {
 // Public Functions
 impl<'a> Help<'a> {
-    /// Create a new Help instance.
+    /// Create a new `Help` instance.
    pub fn new(w: &'a mut Write, next_line_help: bool, hide_pv: bool, color: bool) -> Self {
        Help {
            writer: w,
--- a/src/app/mod.rs
+++ b/src/app/mod.rs
@ -30,12 +30,12 @@ use errors::Result as ClapResult;
 /// Used to create a representation of a command line program and all possible command line
 /// arguments. Application settings are set using the "builder pattern" with the
-/// `.get_matches()` family of methods being the terminal methods that starts the runtime-parsing
+/// [`App::get_matches`] family of methods being the terminal methods that starts the
-/// process. These methods then return information about the user supplied arguments (or lack there
+/// runtime-parsing process. These methods then return information about the user supplied
-/// of).
+/// arguments (or lack there of).
 ///
 /// **NOTE:** There aren't any mandatory "options" that one must set. The "options" may
-/// also appear in any order (so long as one of the `App::get_matches*` methods is the last method
+/// also appear in any order (so long as one of the [`App::get_matches`] methods is the last method
 /// called).
 ///
 /// # Examples
@ -55,6 +55,7 @@ use errors::Result as ClapResult;
 ///
 /// // Your program logic starts here...
 /// ```
 /// [`App::get_matches`]: ./struct.App.html#method.get_matches
 #[allow(missing_debug_implementations)]
 pub struct App<'a, 'b>
    where 'a: 'b
@ -80,10 +81,10 @@ impl<'a, 'b> App<'a, 'b> {
        App { p: Parser::with_name(n.into()) }
    }
-    /// Creates a new instace of `App` from a .yml (YAML) file. A full example of supported YAML
+    /// Creates a new instace of [`App`] from a .yml (YAML) file. A full example of supported YAML
-    /// objects can be found in `examples/17_yaml.rs` and `examples/17_yaml.yml`. One great use for
+    /// objects can be found in [`examples/17_yaml.rs`] and [`examples/17_yaml.yml`]. One great use
-    /// using YAML is when supporting multiple languages and dialects, as each language could be a
+    /// for using YAML is when supporting multiple languages and dialects, as each language could
-    /// distinct YAML file and determined at compiletime via `cargo` "features" in your
+    /// be a distinct YAML file and determined at compiletime via `cargo` "features" in your
    /// `Cargo.toml`
    ///
    /// In order to use this function you must compile `clap` with the `features = ["yaml"]` in
@ -95,14 +96,14 @@ impl<'a, 'b> App<'a, 'b> {
    ///
    /// # Panics
    ///
-    /// The YAML file must be properly formatted or this function will panic!(). A good way to
+    /// The YAML file must be properly formatted or this function will [`panic!`]. A good way to
    /// ensure this doesn't happen is to run your program with the `--help` switch. If this passes
    /// without error, you needn't worry because the YAML is properly formatted.
    ///
    /// # Examples
    ///
    /// The following example shows how to load a properly formatted YAML file to build an instnace
-    /// of an `App` struct.
+    /// of an [`App`] struct.
    ///
    /// ```ignore
    /// # use clap::App;
@ -111,6 +112,10 @@ impl<'a, 'b> App<'a, 'b> {
    ///
    /// // continued logic goes here, such as `app.get_matches()` etc.
    /// ```
    /// [`App`]: ./struct.App.html
    /// [`examples/17_yaml.rs`]: https://github.com/kbknapp/clap-rs/blob/master/examples/17_yaml.rs
    /// [`examples/17_yaml.yml`]: https://github.com/kbknapp/clap-rs/blob/master/examples/17_yaml.yml
    /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
    #[cfg(feature = "yaml")]
    pub fn from_yaml(yaml: &'a Yaml) -> App<'a, 'a> {
        App::from(yaml)
@ -120,9 +125,9 @@ impl<'a, 'b> App<'a, 'b> {
    /// request the help information with `--help` or `-h`.
    ///
    /// **Pro-tip:** If you turn on unstable features you can use `clap`s
-    /// convienience macro `crate_authors!` to automatically set your
+    /// convienience macro [`crate_authors!`] to automatically set your
    /// application's author to the same thing as your crate at compile time.
-    /// See the `examples/`
+    /// See the [`examples/`]
    /// directory for more information
    ///
    /// # Examples
@ -133,6 +138,8 @@ impl<'a, 'b> App<'a, 'b> {
    ///      .author("Me, me@mymain.com")
    /// # ;
    /// ```
    /// [`crate_authors!`]: ./macro.crate_authors!.html
    /// [`examples/`]: https://github.com/kbknapp/clap-rs/tree/master/examples
    pub fn author<S: Into<&'b str>>(mut self, author: S) -> Self {
        self.p.meta.author = Some(author.into());
        self
@ -145,7 +152,7 @@ impl<'a, 'b> App<'a, 'b> {
    /// **Pro-tip:** When building things such as third party `cargo` subcommands, this setting
    /// **should** be used!
    ///
-    /// **NOTE:** This command **should not** be used for `SubCommand`s.
+    /// **NOTE:** This command **should not** be used for [`SubCommand`]s.
    ///
    /// # Examples
    ///
@ -155,6 +162,7 @@ impl<'a, 'b> App<'a, 'b> {
    ///      .bin_name("my_binary")
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    pub fn bin_name<S: Into<String>>(mut self, name: S) -> Self {
        self.p.meta.bin_name = Some(name.into());
        self
@ -213,8 +221,8 @@ impl<'a, 'b> App<'a, 'b> {
    /// Sets a string of the version number to be displayed when displaying version or help
    /// information.
    ///
-    /// **Pro-tip:** Use `clap`s convienience macro `crate_version!` to automatically set your
+    /// **Pro-tip:** Use `clap`s convienience macro [`crate_version!`] to automatically set your
-    /// application's version to the same thing as your crate at compile time. See the `examples/`
+    /// application's version to the same thing as your crate at compile time. See the [`examples/`]
    /// directory for more information
    ///
    /// # Examples
@ -225,6 +233,8 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .version("v0.1.24")
    /// # ;
    /// ```
    /// [`crate_authors!`]: ./macro.crate_authors!.html
    /// [`examples/`]: https://github.com/kbknapp/clap-rs/tree/master/examples
    pub fn version<S: Into<&'b str>>(mut self, ver: S) -> Self {
        self.p.meta.version = Some(ver.into());
        self
@ -233,7 +243,7 @@ impl<'a, 'b> App<'a, 'b> {
    /// Sets a custom usage string to override the auto-generated usage string.
    ///
    /// This will be displayed to the user when errors are found in argument parsing, or when you
-    /// call `ArgMatches::usage`
+    /// call [`ArgMatches::usage`]
    ///
    /// **CAUTION:** Using this setting disables `clap`s "context-aware" usage strings. After this
    /// setting is set, this will be the only usage string displayed to the user!
@ -253,6 +263,7 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .usage("myapp [-clDas] <some_file>")
    /// # ;
    /// ```
    /// [`ArgMatches::usage`]: ./struct.ArgMatches.html#method.usage
    pub fn usage<S: Into<&'b str>>(mut self, usage: S) -> Self {
        self.p.meta.usage_str = Some(usage.into());
        self
@ -267,7 +278,7 @@ impl<'a, 'b> App<'a, 'b> {
    ///
    /// **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 `.help()` for them as well.
+    /// specify a [`Arg::help`] for them as well.
    ///
    /// # Examples
    ///
@ -291,19 +302,23 @@ impl<'a, 'b> App<'a, 'b> {
    ///            work             Do some work")
    /// # ;
    /// ```
    /// [`Arg::help`]: ./struct.Arg.html#method.help
    pub fn help<S: Into<&'b str>>(mut self, help: S) -> Self {
        self.p.meta.help_str = Some(help.into());
        self
    }
-    /// Sets the short version of the `help` argument without the preceding `-`.
+    /// Sets the [`short`] for the auto-generated `help` argument.
    ///
-    /// By default `clap` automatically assigns `h`, but this can be overridden by defining your
+    /// By default `clap` automatically assigns `h`, but this can be overridden if you have a
-    /// own argument with a lowercase `h` as the `short`. `clap` lazily generates these help
+    /// different argument which you'd prefer to use the `-h` short with. This can be done by
-    /// arguments **after** you've defined any arguments of your own.
+    /// defining your own argument with a lowercase `h` as the [`short`].
    ///
    /// `clap` lazily generates these `help` arguments **after** you've defined any arguments of
    /// your own.
    ///
    /// **NOTE:** Any leading `-` characters will be stripped, and only the first
-    /// non `-` chacter will be used as the `short` version
+    /// non `-` chacter will be used as the [`short`] version
    ///
    /// # Examples
    ///
@ -313,16 +328,20 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .help_short("H") // Using an uppercase `H` instead of the default lowercase `h`
    /// # ;
    /// ```
    /// [`short`]: ./struct.Arg.html#method.short
    pub fn help_short<S: AsRef<str> + 'b>(mut self, s: S) -> Self {
        self.p.help_short(s.as_ref());
        self
    }
-    /// Sets the short version of the `version` argument without the preceding `-`.
+    /// Sets the [`short`] for the auto-generated `version` argument.
    ///
-    /// By default `clap` automatically assigns `V`, but this can be overridden by defining your
+    /// By default `clap` automatically assigns `V`, but this can be overridden if you have a
-    /// own argument with a uppercase `V` as the `short`. `clap` lazily generates these version
+    /// different argument which you'd prefer to use the `-V` short with. This can be done by
-    /// arguments **after** you've defined any arguments of your own.
+    /// defining your own argument with an uppercase `V` as the [`short`].
    ///
    /// `clap` lazily generates these `version` arguments **after** you've defined any arguments of
    /// your own.
    ///
    /// **NOTE:** Any leading `-` characters will be stripped, and only the first
    /// non `-` chacter will be used as the `short` version
@ -335,6 +354,7 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .version_short("v") // Using a lowercase `v` instead of the default capital `V`
    /// # ;
    /// ```
    /// [`short`]: ./struct.Arg.html#method.short
    pub fn version_short<S: AsRef<str>>(mut self, s: S) -> Self {
        self.p.version_short(s.as_ref());
        self
@ -373,9 +393,9 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// Enables a single Application level settings.
+    /// Enables a single command, or [`SubCommand`], level settings.
    ///
-    /// See `AppSettings` for a full list of possibilities and examples.
+    /// See [`AppSettings`] for a full list of possibilities and examples.
    ///
    /// # Examples
    ///
@ -386,14 +406,16 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .setting(AppSettings::WaitOnError)
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`AppSettings`]: ./enum.AppSettings.html
    pub fn setting(mut self, setting: AppSettings) -> Self {
        self.p.set(setting);
        self
    }
-    /// Enables multiple Application level settings
+    /// Enables multiple command, or [`SubCommand`], level settings
    ///
-    /// See `AppSettings` for a full list of possibilities and examples.
+    /// See [`AppSettings`] for a full list of possibilities and examples.
    ///
    /// # Examples
    ///
@ -404,6 +426,8 @@ impl<'a, 'b> App<'a, 'b> {
    ///                  AppSettings::WaitOnError])
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`AppSettings`]: ./enum.AppSettings.html
    pub fn settings(mut self, settings: &[AppSettings]) -> Self {
        for s in settings {
            self.p.set(*s);
@ -411,7 +435,7 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// Adds an argument to the list of valid possibilties.
+    /// Adds an [argument] to the list of valid possibilties.
    ///
    /// # Examples
    ///
@ -431,12 +455,13 @@ impl<'a, 'b> App<'a, 'b> {
    ///     )
    /// # ;
    /// ```
    /// [argument]: ./struct.Arg.html
    pub fn arg<A: Borrow<Arg<'a, 'b>> + 'a>(mut self, a: A) -> Self {
        self.p.add_arg(a.borrow());
        self
    }
-    /// Adds multiple arguments to the list of valid possibilties
+    /// Adds multiple [arguments] to the list of valid possibilties
    ///
    /// # Examples
    ///
@ -449,6 +474,7 @@ impl<'a, 'b> App<'a, 'b> {
    ///     )
    /// # ;
    /// ```
    /// [arguments]: ./struct.Arg.html
    pub fn args(mut self, args: &[Arg<'a, 'b>]) -> Self {
        for arg in args {
            self.p.add_arg(arg);
@ -456,11 +482,11 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// A convienience method for adding a single argument from a usage type string. The string
+    /// A convienience method for adding a single [argument] from a usage type string. The string
-    /// used follows the same rules and syntax as `Arg::from_usage()`
+    /// used follows the same rules and syntax as [`Arg::from_usage`]
    ///
    /// **NOTE:** The downside to using this method is that you can not set any additional
-    /// properties of the `Arg` other than what `Arg::from_usage()` supports.
+    /// properties of the [`Arg`] other than what [`Arg::from_usage`] supports.
    ///
    /// # Examples
    ///
@ -470,16 +496,19 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .arg_from_usage("-c --config=<FILE> 'Sets a configuration file to use'")
    /// # ;
    /// ```
    /// [arguments]: ./struct.Arg.html
    /// [`Arg`]: ./struct.Arg.html
    /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage
    pub fn arg_from_usage(mut self, usage: &'a str) -> Self {
        self.p.add_arg(&Arg::from_usage(usage));
        self
    }
-    /// Adds multiple arguments at once from a usage string, one per line. See `Arg::from_usage()`
+    /// Adds multiple [arguments] at once from a usage string, one per line. See
-    /// for details on the syntax and rules supported.
+    /// [`Arg::from_usage`] for details on the syntax and rules supported.
    ///
-    /// **NOTE:** Like `App::arg_from_usage()` the downside is you only set properties for the
+    /// **NOTE:** Like [`App::arg_from_usage`] the downside is you only set properties for the
-    /// `Arg`s which `Arg::from_usage()` supports.
+    /// [`Arg`]s which [`Arg::from_usage`] supports.
    ///
    /// # Examples
    ///
@ -493,6 +522,10 @@ impl<'a, 'b> App<'a, 'b> {
    ///     )
    /// # ;
    /// ```
    /// [arguments]: ./struct.Arg.html
    /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage
    /// [`App::arg_from_usage`]: ./struct.App.html#method.arg_from_usage
    /// [`Arg`]: ./struct.Arg.html
    pub fn args_from_usage(mut self, usage: &'a str) -> Self {
        for line in usage.lines() {
            let l = line.trim();
@ -504,10 +537,10 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// Allows adding a subcommand alias, which function as "hidden" subcommands that automatically
+    /// Allows adding a [`SubCommand`] alias, which function as "hidden" subcommands that
-    /// dispatch as if this subcommand was used. This is more efficient, and easier than creating
+    /// automatically dispatch as if this subcommand was used. This is more efficient, and easier
-    /// multiple hidden subcommands as one only needs to check for the existing of this command,
+    /// than creating multiple hidden subcommands as one only needs to check for the existing of
-    /// and not all vairants.
+    /// this command, and not all vairants.
    ///
    /// # Examples
    ///
@ -519,6 +552,7 @@ impl<'a, 'b> App<'a, 'b> {
    ///             .get_matches_from(vec!["myprog", "do-stuff"]);
    /// assert_eq!(m.subcommand_name(), Some("test"));
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    pub fn alias<S: Into<&'b str>>(mut self, name: S) -> Self {
        if let Some(ref mut als) = self.p.meta.aliases {
            als.push(name.into());
@ -528,10 +562,10 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// Allows adding subcommand aliases, which function as "hidden" subcommands that automatically
+    /// Allows adding [`SubCommand`] aliases, which function as "hidden" subcommands that
-    /// dispatch as if this subcommand was used. This is more efficient, and easier than creating
+    /// automatically dispatch as if this subcommand was used. This is more efficient, and easier
-    /// multiple hidden subcommands as one only needs to check for the existing of this command,
+    /// than creating multiple hidden subcommands as one only needs to check for the existing of
-    /// and not all vairants.
+    /// this command, and not all vairants.
    ///
    /// # Examples
    ///
@ -547,6 +581,7 @@ impl<'a, 'b> App<'a, 'b> {
    ///             .get_matches_from(vec!["myprog", "do-tests"]);
    /// assert_eq!(m.subcommand_name(), Some("test"));
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    pub fn aliases(mut self, names: &[&'b str]) -> Self {
        if let Some(ref mut als) = self.p.meta.aliases {
            for n in names {
@ -558,24 +593,25 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// Adds an `ArgGroup` to the application. `ArgGroup`s are a family of related arguments. By
+    /// Adds an [`ArgGroup`] to the application. [`ArgGroup`]s are a family of related arguments.
-    /// placing them in a logical group, you can build easier requirement and exclusion rules. For
+    /// By placing them in a logical group, you can build easier requirement and exclusion rules.
-    /// instance, you can make an entire `ArgGroup` required, meaning that one (and *only* one)
+    /// For instance, you can make an entire [`ArgGroup`] required, meaning that one (and *only*
-    /// argument from that group must be present at runtime.
+    /// one) argument from that group must be present at runtime.
    ///
-    /// You can also do things such as name an `ArgGroup` as a conflict to another argument.
+    /// You can also do things such as name an [`ArgGroup`] as a conflict to another argument.
    /// Meaning any of the arguments that belong to that group will cause a failure if present with
    /// the conflicting argument.
    ///
-    /// Another added benfit of `ArgGroup`s is that you can extract a value from a group instead of
+    /// Another added benfit of [`ArgGroup`]s is that you can extract a value from a group instead
-    /// determining exactly which argument was used.
+    /// of determining exactly which argument was used.
    ///
-    /// Finally, using `ArgGroup`s to ensure exclusion between arguments is another very common use
+    /// Finally, using [`ArgGroup`]s to ensure exclusion between arguments is another very common
    /// use
    ///
    /// # Examples
    ///
-    /// The following example demonstrates using an `ArgGroup` to ensure that one, and only one, of
+    /// The following example demonstrates using an [`ArgGroup`] to ensure that one, and only one,
-    /// the arguments from the specified group is present at runtime.
+    /// of the arguments from the specified group is present at runtime.
    ///
    /// ```no_run
    /// # use clap::{App, ArgGroup};
@ -590,12 +626,13 @@ impl<'a, 'b> App<'a, 'b> {
    ///          .required(true))
    /// # ;
    /// ```
    /// [`ArgGroup`]: ./struct.ArgGroup.html
    pub fn group(mut self, group: ArgGroup<'a>) -> Self {
        self.p.add_group(group);
        self
    }
-    /// Adds multiple `ArgGroup`s to the application at once.
+    /// Adds multiple [`ArgGroup`]s to the [`App`] at once.
    ///
    /// # Examples
    ///
@ -618,6 +655,8 @@ impl<'a, 'b> App<'a, 'b> {
    ///     ])
    /// # ;
    /// ```
    /// [`ArgGroup`]: ./struct.ArgGroup.html
    /// [`App`]: ./struct.App.html
    pub fn groups(mut self, groups: &[ArgGroup<'a>]) -> Self {
        for g in groups {
            self = self.group(g.into());
@ -625,10 +664,10 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// Adds a subcommand to the list of valid possibilties. Subcommands are effectively sub-apps,
+    /// Adds a [`SubCommand`] to the list of valid possibilties. Subcommands are effectively
-    /// because they can contain their own arguments, subcommands, version, usage, etc. They also
+    /// sub-[`App`]s, because they can contain their own arguments, subcommands, version, usage,
-    /// function just like apps, in that they get their own auto generated help, version, and
+    /// etc. They also function just like [`App`]s, in that they get their own auto generated help,
-    /// usage.
+    /// version, and usage.
    ///
    /// # Examples
    ///
@ -640,17 +679,19 @@ impl<'a, 'b> App<'a, 'b> {
    ///         .arg_from_usage("<config> 'Required configuration file to use'"))
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`App`]: ./struct.App.html
    pub fn subcommand(mut self, subcmd: App<'a, 'b>) -> Self {
        self.p.add_subcommand(subcmd);
        self
    }
-    /// Adds multiple subcommands to the list of valid possibilties by iterating over a Vec of
+    /// Adds multiple subcommands to the list of valid possibilties by iterating over an
-    /// `SubCommand`s
+    /// [`IntoIterator`] of [`SubCommand`]s
    ///
    /// # Examples
    ///
-    /// ```no_run
+    /// ```rust
    /// # use clap::{App, Arg, SubCommand};
    /// # App::new("myprog")
    /// .subcommands( vec![
@ -659,6 +700,8 @@ impl<'a, 'b> App<'a, 'b> {
    ///        SubCommand::with_name("debug").about("Controls debug functionality")])
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`IntoIterator`]: https://doc.rust-lang.org/std/iter/trait.IntoIterator.html
    pub fn subcommands<I>(mut self, subcmds: I) -> Self
        where I: IntoIterator<Item = App<'a, 'b>>
    {
@ -668,7 +711,7 @@ impl<'a, 'b> App<'a, 'b> {
        self
    }
-    /// Allows custom ordering of subcommands within the help message. Subcommands with a lower
+    /// Allows custom ordering of [`SubCommand`]s within the help message. Subcommands with a lower
    /// value will be displayed first in the help message. This is helpful when one would like to
    /// emphasise frequently used subcommands, or prioritize those towards the top of the list.
    /// Duplicate values **are** allowed. Subcommands with duplicate display orders will be
@ -714,44 +757,49 @@ impl<'a, 'b> App<'a, 'b> {
    ///     beta    I should be first!
    ///     alpha   Some help and text
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    pub fn display_order(mut self, ord: usize) -> Self {
        self.p.meta.disp_ord = ord;
        self
    }
-    /// Prints the full help message to `io::stdout()` using a `BufWriter`
+    /// Prints the full help message to [`io::stdout()`] using a [`BufWriter`]
    ///
    /// # Examples
    ///
-    /// ```no_run
+    /// ```rust
    /// # use clap::App;
    /// let app = App::new("myprog");
    /// app.print_help();
    /// ```
    /// [`io::stdout()`]: https://doc.rust-lang.org/std/io/fn.stdout.html
    /// [`BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html
    pub fn print_help(&self) -> ClapResult<()> {
        let out = io::stdout();
        let mut buf_w = BufWriter::new(out.lock());
        self.write_help(&mut buf_w)
    }
-    /// Writes the full help message to the user to a `io::Write` object
+    /// Writes the full help message to the user to a [`io::Write`] object
    ///
    /// # Examples
    ///
-    /// ```no_run
+    /// ```rust
    /// # use clap::App;
    /// use std::io;
    /// let mut app = App::new("myprog");
    /// let mut out = io::stdout();
    /// app.write_help(&mut out).ok().expect("failed to write to stdout");
    /// ```
    /// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
    pub fn write_help<W: Write>(&self, w: &mut W) -> ClapResult<()> {
        Help::write_app_help(w, &self)
    }
    /// Starts the parsing process, upon a failed parse an error will be displayed to the user and
-    /// the process with exit with the appropriate error code. By default this method gets matches
+    /// the process with exit with the appropriate error code. By default this method gets all user
-    /// from `env::args_os`
+    /// provided arguments from [`env::args_os`] in order to allow for invalid UTF-8 code points,
    /// which are legal on many platforms.
    ///
    /// # Examples
    ///
@ -761,18 +809,18 @@ impl<'a, 'b> App<'a, 'b> {
    ///     // Args and options go here...
    ///     .get_matches();
    /// ```
    /// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html
    pub fn get_matches(self) -> ArgMatches<'a> {
        self.get_matches_from(&mut env::args_os())
    }
-    /// Starts the parsing process. This method will return a `Result` type instead of exiting the
+    /// Starts the parsing process. This method will return a [`clap::Result`] type instead of exiting
-    /// the process on failed parse. By default this method gets matches
+    /// the the process on failed parse. By default this method gets matches from [`env::args_os`]
    /// from `env::args_os`
    ///
    /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
-    /// used. It will return an error, where the `kind` is a `ErrorKind::HelpDisplayed`
+    /// used. It will return a [`clap::Error`], where the [`kind`] is a
-    /// or `ErrorKind::VersionDisplayed` respectively. You must call `error.exit()` or
+    /// [`ErrorKind::HelpDisplayed`] or [`ErrorKind::VersionDisplayed`] respectively. You must call
-    /// perform a `std::process::exit`.
+    /// [`Error::exit`] or perform a [`std::process::exit`].
    ///
    /// # Examples
    ///
@ -783,17 +831,25 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .get_matches_safe()
    ///     .unwrap_or_else( |e| e.exit() );
    /// ```
    /// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html
    /// [`ErrorKind::HelpDisplayed`]: ./enum.ErrorKind.html#variant.HelpDisplayed
    /// [`ErrorKind::VersionDisplayed`]: ./enum.ErrorKind.html#variant.VersionDisplayed
    /// [`Error::exit`]: ./struct.Error.html#method.exit
    /// [`std::process::exit`]: https://doc.rust-lang.org/std/process/fn.exit.html
    /// [`clap::Result`]: ./type.Result.html
    /// [`clap::Error`]: ./struct.Error.html
    /// [`kind`]: ./struct.Error.html
    pub fn get_matches_safe(self) -> ClapResult<ArgMatches<'a>> {
        // Start the parsing
        self.get_matches_from_safe(&mut env::args_os())
    }
-    /// Starts the parsing process. Like `App::get_matches` this method does not return a `Result`
+    /// Starts the parsing process. Like [`App::get_matches`] this method does not return a [`clap::Result`]
    /// and will automatically exit with an error message. This method, however, lets you specify
-    /// what iterator to use when performing matches, such as a `Vec` of your making.
+    /// what iterator to use when performing matches, such as a [`Vec`] of your making.
    ///
    /// **NOTE:** The first argument will be parsed as the binary name unless
-    /// `AppSettings::NoBinaryName` is used
+    /// [`AppSettings::NoBinaryName`] is used
    ///
    /// # Examples
    ///
@ -805,6 +861,10 @@ impl<'a, 'b> App<'a, 'b> {
    ///     // Args and options go here...
    ///     .get_matches_from(arg_vec);
    /// ```
    /// [`App::get_matches`]: ./struct.App.html#method.get_matches
    /// [`clap::Result`]: ./type.Result.html
    /// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
    /// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
    pub fn get_matches_from<I, T>(mut self, itr: I) -> ArgMatches<'a>
        where I: IntoIterator<Item = T>,
              T: Into<OsString>
@ -815,16 +875,16 @@ impl<'a, 'b> App<'a, 'b> {
        })
    }
-    /// Starts the parsing process. A combination of `App::get_matches_from`, and
+    /// Starts the parsing process. A combination of [`App::get_matches_from`], and
-    /// `App::get_matches_safe`
+    /// [`App::get_matches_safe`]
    ///
    /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
-    /// used. It will return an error, where the `kind` is a `ErrorKind::HelpDisplayed`
+    /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::HelpDisplayed`]
-    /// or `ErrorKind::VersionDisplayed` respectively. You must call `error.exit()` or
+    /// or [`ErrorKind::VersionDisplayed`] respectively. You must call [`Error::exit`] or
-    /// perform a `std::process::exit` yourself.
+    /// perform a [`std::process::exit`] yourself.
    ///
    /// **NOTE:** The first argument will be parsed as the binary name unless
-    /// `AppSettings::NoBinaryName` is used
+    /// [`AppSettings::NoBinaryName`] is used
    ///
    /// # Examples
    ///
@ -837,6 +897,16 @@ impl<'a, 'b> App<'a, 'b> {
    ///     .get_matches_from_safe(arg_vec)
    ///     .unwrap_or_else( |e| { panic!("An error occurs: {}", e) });
    /// ```
    /// [`App::get_matches_from`]: ./struct.App.html#method.get_matches_from
    /// [`App::get_matches_safe`]: ./struct.App.html#method.get_matches_safe
    /// [`ErrorKind::HelpDisplayed`]: ./enum.ErrorKind.html#variant.HelpDisplayed
    /// [`ErrorKind::VersionDisplayed`]: ./enum.ErrorKind.html#variant.VersionDisplayed
    /// [`Error::exit`]: ./struct.Error.html#method.exit
    /// [`std::process::exit`]: https://doc.rust-lang.org/std/process/fn.exit.html
    /// [`clap::Error`]: ./struct.Error.html
    /// [`Error::exit`]: ./struct.Error.html#method.exit
    /// [`kind`]: ./struct.Error.html
    /// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
    pub fn get_matches_from_safe<I, T>(mut self, itr: I) -> ClapResult<ArgMatches<'a>>
        where I: IntoIterator<Item = T>,
              T: Into<OsString>
@ -844,12 +914,12 @@ impl<'a, 'b> App<'a, 'b> {
        self.get_matches_from_safe_borrow(itr)
    }
-    /// Starts the parsing process without consuming the `App` struct `self`. This is normally not
+    /// Starts the parsing process without consuming the [`App`] struct `self`. This is normally not
-    /// the desired functionality, instead prefer `App::get_matches_from_safe` which *does*
+    /// the desired functionality, instead prefer [`App::get_matches_from_safe`] which *does*
    /// consume `self`.
    ///
    /// **NOTE:** The first argument will be parsed as the binary name unless
-    /// `AppSettings::NoBinaryName` is used
+    /// [`AppSettings::NoBinaryName`] is used
    ///
    /// # Examples
    ///
@ -862,6 +932,9 @@ impl<'a, 'b> App<'a, 'b> {
    /// let matches = app.get_matches_from_safe_borrow(arg_vec)
    ///     .unwrap_or_else( |e| { panic!("An error occurs: {}", e) });
    /// ```
    /// [`App`]: ./struct.App.html
    /// [`App::get_matches_from_safe`]: ./struct.App.html#method.get_matches_from_safe
    /// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
    pub fn get_matches_from_safe_borrow<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches<'a>>
        where I: IntoIterator<Item = T>,
              T: Into<OsString>
--- a/src/app/settings.rs
+++ b/src/app/settings.rs
@ -77,16 +77,18 @@ impl AppFlags {
    }
 }
-/// Application level settings, which affect how `App` operates
+/// Application level settings, which affect how [`App`] operates
 ///
 /// **NOTE:** When these settings are used, they apply only to current command, and are *not*
 /// propagated down or up through child or parent subcommands
 ///
 /// [`App`]: ./struct.App.html
 #[derive(Debug, PartialEq, Copy, Clone)]
 pub enum AppSettings {
-    /// Allows subcommands to override all requirements of the parent command. For example
+    /// Allows [`SubCommand`]s to override all requirements of the parent command. For example if you
-    /// if you had a subcommand or top level application which had a required argument that
+    /// had a subcommand or top level application which had a required argument that are only
-    /// are only required as long as there is no subcommand present, using this setting would allow
+    /// required as long as there is no subcommand present, using this setting would allow you set
-    /// you set those arguments to `required(true)` and yet receive no error so long as the user
+    /// those arguments to [`Arg::required(true)`] and yet receive no error so long as the user
    /// uses a valid subcommand instead.
    ///
    /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements)
@ -124,10 +126,13 @@ pub enum AppSettings {
    /// assert!(noerr.is_ok());
    /// # ;
    /// ```
    /// [`Arg::required(true)`]: ./struct.Arg.html#method.required
    /// [`SubCommand`]: ./struct.SubCommand.html
    SubcommandsNegateReqs,
-    /// Allows specifying that if no subcommand is present at runtime, error and exit gracefully
+    /// Allows specifying that if no [`SubCommand`] is present at runtime, error and exit
    /// gracefully
    ///
-    /// **NOTE:** This defaults to false (subcommands do *not* need to be present)
+    /// **NOTE:** This defaults to `false` (subcommands do *not* need to be present)
    ///
    /// # Examples
    ///
@ -143,11 +148,12 @@ pub enum AppSettings {
    /// assert_eq!(err.unwrap_err().kind, ErrorKind::MissingSubcommand);
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    SubcommandRequired,
    /// Specifies that the help text should be displayed (and then exit gracefully), if no
    /// arguments are present at runtime (i.e. an empty run such as, `$ myprog`.
    ///
-    /// **NOTE:** Subcommands count as arguments
+    /// **NOTE:** [`SubCommand`]s count as arguments
    ///
    /// # Examples
    ///
@ -157,9 +163,10 @@ pub enum AppSettings {
    ///     .setting(AppSettings::ArgRequiredElseHelp)
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    ArgRequiredElseHelp,
-    /// Specifies to version of the current command for all child subcommands. (Defaults to false;
+    /// Specifies to use the version of the current command for all child [`SubCommand`]. (Defaults
-    /// subcommands have independant version strings from their parents)
+    /// to `false`; subcommands have independant version strings from their parents)
    ///
    /// **NOTE:** The version for the current command **and** this setting must be set **prior** to
    /// adding any child subcommands
@ -176,9 +183,10 @@ pub enum AppSettings {
    /// // running `$ myprog test --version` will display
    /// // "myprog-test v1.1"
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    GlobalVersion,
-    /// Disables `-V` and `--version` for all subcommands (Defaults to false; subcommands have
+    /// Disables `-V` and `--version` for all [`SubCommand`]s (Defaults to `false`; subcommands
-    /// version flags)
+    /// *do* have version flags)
    ///
    /// **NOTE:** This setting must be set **prior** adding any subcommands
    ///
@ -196,9 +204,12 @@ pub enum AppSettings {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    VersionlessSubcommands,
    /// Groups flags and options together presenting a more unified help message (a la `getopts` or
-    /// `docopt` style). The default is the auto-generated help message groups flags, options
+    /// `docopt` style).
    ///
    /// The default is that the auto-generated help message will group flags, and options
    /// separately.
    ///
    /// **NOTE:** This setting is cosmetic only and does not affect any functionality.
@ -220,7 +231,7 @@ pub enum AppSettings {
    /// Windows where a user tries to open the binary by double-clicking instead of using the
    /// command line.
    ///
-    /// **NOTE:** This setting is **not** recursive with subcommands, meaning if you wish this
+    /// **NOTE:** This setting is **not** recursive with [`SubCommand`]s, meaning if you wish this
    /// behavior for all subcommands, you must set this on each command (needing this is extremely
    /// rare)
    ///
@ -232,16 +243,17 @@ pub enum AppSettings {
    ///     .setting(AppSettings::WaitOnError)
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    WaitOnError,
    /// Specifies that the help text should be displayed (and then exit gracefully), if no
-    /// subcommands are present at runtime (i.e. an empty run such as, `$ myprog`.
+    /// [`SubCommand`]s are present at runtime (i.e. an empty run such as, `$ myprog`.
    ///
-    /// **NOTE:** This should *not* be used with `.subcommand_required()` as they do the same
+    /// **NOTE:** This should *not* be used with [`AppSettings::SubcommandRequired`] as they do
-    /// thing, except this prints the help text, and the other prints an error.
+    /// nearly same thing; this prints the help text, and the other prints an error.
    ///
    /// **NOTE:** If the user specifies arguments at runtime, but no subcommand the help text will
    /// still be displayed and exit. If this is *not* the desired result, consider using
-    /// `ArgRequiredElseHelp` instead.
+    /// [`AppSettings::ArgRequiredElseHelp`] instead.
    ///
    /// # Examples
    ///
@ -251,8 +263,11 @@ pub enum AppSettings {
    ///     .setting(AppSettings::SubcommandRequiredElseHelp)
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired
    /// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp
    SubcommandRequiredElseHelp,
-    /// Specifies that this subcommand should be hidden from help messages
+    /// Specifies that this [`SubCommand`] should be hidden from help messages
    ///
    /// # Examples
    ///
@ -263,14 +278,15 @@ pub enum AppSettings {
    ///     .setting(AppSettings::Hidden))
    /// # ;
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    Hidden,
    /// Specifies that the final positional argument is a "VarArg" and that `clap` should not
    /// attempt to parse any further args.
    ///
    /// The values of the trailing positional argument will contain all args from itself on.
    ///
-    /// **NOTE:** The final positional argument **must** have `.multiple(true)` or the usage string
+    /// **NOTE:** The final positional argument **must** have [`Arg::multiple(true)`] or the usage
-    /// equivalent.
+    /// string equivalent.
    ///
    /// # Examples
    ///
@ -284,6 +300,7 @@ pub enum AppSettings {
    /// let trail: Vec<&str> = m.values_of("cmd").unwrap().collect();
    /// assert_eq!(trail, ["arg1", "-r", "val1"]);
    /// ```
    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
    TrailingVarArg,
    /// Specifies that the parser should not assume the first argument passed is the binary name.
    /// This is normally the case when using a "daemon" style mode, or an interactive CLI where one
@ -302,13 +319,14 @@ pub enum AppSettings {
    /// assert_eq!(cmds, ["command", "set"]);
    /// ```
    NoBinaryName,
-    /// Specifies that an unexpected argument positional arguments which would otherwise cause a
+    /// Specifies that an unexpected positional argument, which would otherwise cause a
-    /// `ErrorKind::UnknownArgument` error, should instead be treated as a subcommand in the
+    /// [`ErrorKind::UnknownArgument`] error, should instead be treated as a [`SubCommand`] within
-    /// `ArgMatches` struct.
+    /// the [`ArgMatches`] struct.
    ///
    /// **NOTE:** Use this setting with caution, as a truly unexpected argument (i.e. one that is
-    /// *NOT* an external subcommand) will not cause an error and instead be treatd as a potential
+    /// *NOT* an external subcommand) will **not** cause an error and instead be treatd as a
-    /// subcommand. You shoud inform the user appropriatly.
+    /// potential subcommand. One should check for such cases manually and inform the user
    /// appropriatly.
    ///
    /// # Examples
    ///
@ -331,12 +349,15 @@ pub enum AppSettings {
    ///     _ => {},
    /// }
    /// ```
    /// [`ErrorKind::UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`ArgMatches`]: ./struct.ArgMatches.html
    AllowExternalSubcommands,
    /// Specifies that any invalid UTF-8 code points should be treated as an error and fail
-    /// with a `ErrorKind::InvalidUtf8` error.
+    /// with a [`ErrorKind::InvalidUtf8`] error.
    ///
-    /// **NOTE:** This rule only applies to argument values, as flags, options, and subcommands
+    /// **NOTE:** This rule only applies to argument values. Things such as flags, options, and
-    /// themselves only allow valid UTF-8 code points.
+    /// [`SubCommand`]s themselves only allow valid UTF-8 code points.
    ///
    /// # Platform Specific
    ///
@ -360,16 +381,19 @@ pub enum AppSettings {
    /// assert_eq!(m.unwrap_err().kind, ErrorKind::InvalidUtf8);
    /// }
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`ErrorKind::InvalidUtf8`]: ./enum.ErrorKind.html#variant.InvalidUtf8
    StrictUtf8,
    /// Specifies that any invalid UTF-8 code points should *not* be treated as an error. This is
    /// the default behavior of `clap`
    ///
-    /// **NOTE:** Using argument values with invalid UTF-8 code points requires using Either
+    /// **NOTE:** Using argument values with invalid UTF-8 code points requires using
-    /// `ArgMatches::os_value(s)_of` or `ArgMatches::lossy_value(s)_of` for those particular
+    /// [`ArgMatches::os_value_of`], [`ArgMatches::os_values_of`], [`ArgMatches::lossy_value_of`],
-    /// arguments which may contain invalid UTF-8 values
+    /// or [`ArgMatches::lossy_values_of`] for those particular arguments which may contain invalid
    /// UTF-8 values
    ///
-    /// **NOTE:** This rule only applies to  argument values, as flags, options, and subcommands
+    /// **NOTE:** This rule only applies to  argument values, as flags, options, and
-    /// themselves only allow valid UTF-8 code points.
+    /// [`SubCommand`]s themselves only allow valid UTF-8 code points.
    ///
    /// # Platform Specific
    ///
@ -394,9 +418,13 @@ pub enum AppSettings {
    /// let m = r.unwrap();
    /// assert_eq!(m.value_of_os("arg").unwrap().as_bytes(), &[0xe9]);
    /// ```
    /// [`ArgMatches::os_value_of`]: ./struct.ArgMatches.html#method.os_value_of
    /// [`ArgMatches::os_values_of`]: ./struct.ArgMatches.html#method.os_values_of
    /// [`ArgMatches::lossy_value_of`]: ./struct.ArgMatches.html#method.lossy_value_of
    /// [`ArgMatches::lossy_values_of`]: ./struct.ArgMatches.html#method.lossy_values_of
    AllowInvalidUtf8,
    /// Specifies that leading hyphens are allowed in argument *values*, such as negative numbers
-    /// `-10`
+    /// `-10` (which would otherwise be parsed as another flag or option)
    ///
    /// **NOTE:** This can only be set application wide and not on a per argument basis.
    ///
@ -425,8 +453,6 @@ pub enum AppSettings {
    HidePossibleValuesInHelp,
    /// Places the help string for all arguments on the line after the argument
    ///
    /// **NOTE:** This setting is cosmetic only and does not affect any functionality.
    ///
    /// # Examples
    ///
    /// ```no_run
@ -436,7 +462,7 @@ pub enum AppSettings {
    ///     .get_matches();
    /// ```
    NextLineHelp,
-    /// Displays the arguments and subcommands in the help message in the order that they were
+    /// Displays the arguments and [`SubCommand`]s in the help message in the order that they were
    /// declared in, vice alphabetically which is the default.
    ///
    /// # Examples
@ -447,6 +473,7 @@ pub enum AppSettings {
    ///     .setting(AppSettings::DeriveDisplayOrder)
    ///     .get_matches();
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    DeriveDisplayOrder,
    /// Uses colorized help messages.
    ///
--- a/src/args/arg.rs
+++ b/src/args/arg.rs
@ -12,7 +12,7 @@ use args::settings::{ArgFlags, ArgSettings};
 /// The abstract representation of a command line argument. Used to set all the options and
 /// relationships that define a valid argument for the program.
 ///
-/// There are two methods for constructing `Arg`s, using the builder pattern and setting options
+/// There are two methods for constructing [`Arg`]s, using the builder pattern and setting options
 /// manually, or using a usage string which is far less verbose but has fewer options. You can also
 /// use a combination of the two methods to achieve the best of both worlds.
 ///
@ -30,6 +30,7 @@ use args::settings::{ArgFlags, ArgSettings};
 /// // Using a usage string (setting a similar argument to the one above)
 /// let input = Arg::from_usage("-i, --input=[FILE] 'Provides an input file to the program'");
 /// ```
 /// [`Arg`]: ./struct.Arg.html
 #[allow(missing_debug_implementations)]
 pub struct Arg<'a, 'b>
    where 'a: 'b
@ -105,11 +106,11 @@ impl<'a, 'b> Default for Arg<'a, 'b> {
 impl<'a, 'b> Arg<'a, 'b> {
-    /// Creates a new instance of `Arg` using a unique string name. The name will be used to get
+    /// Creates a new instance of [`Arg`] using a unique string name. The name will be used to get
    /// information about whether or not the argument was used at runtime, get values, set
    /// relationships with other args, etc..
    ///
-    /// **NOTE:** In the case of arguments that take values (i.e. `takes_value(true)`)
+    /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::takes_value(true)`])
    /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also
    /// be displayed when the user prints the usage/help information of the program.
    ///
@ -120,11 +121,13 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Arg::with_name("config")
    /// # ;
    /// ```
    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
    /// [`Arg`]: ./struct.Arg.html
    pub fn with_name(n: &'a str) -> Self {
        Arg { name: n, ..Default::default() }
    }
-    /// Creates a new instance of `Arg` from a .yml (YAML) file.
+    /// Creates a new instance of [`Arg`] from a .yml (YAML) file.
    ///
    /// # Examples
    ///
@ -133,6 +136,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// let yml = load_yaml!("arg.yml");
    /// let arg = Arg::from_yaml(yml);
    /// ```
    /// [`Arg`]: ./struct.Arg.html
    #[cfg(feature = "yaml")]
    pub fn from_yaml<'y>(y: &'y BTreeMap<Yaml, Yaml>) -> Arg<'y, 'y> {
        // We WANT this to panic on error...so expect() is good.
@ -229,14 +233,14 @@ impl<'a, 'b> Arg<'a, 'b> {
        a
    }
-    /// Creates a new instance of `Arg` from a usage string. Allows creation of basic settings for
+    /// Creates a new instance of [`Arg`] from a usage string. Allows creation of basic settings
-    /// the `Arg`. The syntax is flexible, but there are some rules to follow.
+    /// for the [`Arg`]. The syntax is flexible, but there are some rules to follow.
    ///
    /// **NOTE**: Not all settings may be set using the usage string method. Some properties are
    /// only available via the builder pattern.
    ///
-    /// **NOTE**: Only ASCII values in `from_usage` strings are officially supported. Some UTF-8
+    /// **NOTE**: Only ASCII values are officially supported in [`Arg::from_usage`] strings. Some
-    /// codepoints may work just fine, but this is not guaranteed.
+    /// UTF-8 codepoints may work just fine, but this is not guaranteed.
    ///
    /// # Syntax
    ///
@ -358,6 +362,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// ])
    /// # ;
    /// ```
    /// [`Arg`]: ./struct.Arg.html
    /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage
    pub fn from_usage(u: &'a str) -> Self {
        let parser = UsageParser::from_usage(u);
        parser.parse()
@ -365,17 +371,18 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Sets the short version of the argument without the preceding `-`.
    ///
-    /// By default `clap` automatically assigns `V` and `h` to display version and help information
+    /// By default `clap` automatically assigns `V` and `h` to the auto-generated `version` and
-    /// respectively. You may use `V` or `h` for your own purposes, in which case `clap` simply
+    /// `help` arguments respectively. You may use the uppercase `V` or lowercase `h` for your own
-    /// will not assign those to the displaying of version or help.
+    /// arguments, in which case `clap` simply will not assign those to the auto-generated
    /// `version` or `help` arguments.
    ///
    /// **NOTE:** Any leading `-` characters will be stripped, and only the first
-    /// non `-` character will be used as the `short` version
+    /// non `-` character will be used as the [`short`] version
    ///
    /// # Examples
    ///
-    /// To set `short` use a single valid UTF-8 codepoint. If you supply a leading `-` such as `-c`
+    /// To set [`short`] use a single valid UTF-8 code point. If you supply a leading `-` such as
-    /// it will be stripped.
+    /// `-c`, the `-` will be stripped.
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -384,7 +391,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// # ;
    /// ```
    ///
-    /// Setting `short` allows using the argument via a single hyphen (`-`) such as `-c`
+    /// Setting [`short`] allows using the argument via a single hyphen (`-`) such as `-c`
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -397,6 +404,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// assert!(m.is_present("config"));
    /// ```
    /// [`short`]: ./struct.Arg.html#method.short
    pub fn short<S: AsRef<str>>(mut self, s: S) -> Self {
        self.short = s.as_ref().trim_left_matches(|c| c == '-').chars().nth(0);
        self
@ -404,10 +412,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Sets the long version of the argument without the preceding `--`.
    ///
-    /// By default `clap` automatically assigns `version` and `help` to display version and help
+    /// By default `clap` automatically assigns `version` and `help` to the auto-generated
-    /// information respectively. You may use `version` or `help` for your own purposes, in which
+    /// `version` and `help` arguments respectively. You may use the word `version` or `help` for
-    /// case `clap` simply will not assign those to the displaying of version or help automatically,
+    /// the long form of your own arguments, in which case `clap` simply will not assign those to
-    /// and you will have to do so manually.
+    /// the auto-generated `version` or `help` arguments.
    ///
    /// **NOTE:** Any leading `-` characters will be stripped
    ///
@ -432,7 +440,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///     .arg(Arg::with_name("cfg")
    ///         .long("config"))
    ///     .get_matches_from(vec![
-    ///         "shorttest", "--config"
+    ///         "longtest", "--config"
    ///     ]);
    ///
    /// assert!(m.is_present("cfg"));
@ -447,9 +455,11 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// # Examples
    ///
-    /// Any valid `String` slice is allowed as help (i.e. only valid UTF-8). The one exception is
+    /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
-    /// one wishes to include a newline in the help text. To include a newline **and** be properly
+    /// include a newline in the help text and have the following text be properly aligned with all
-    /// aligned with all other arguments help text, it must be specified via `{n}` instead of `\n`.
+    /// the other help text. To include a newline **and** be properly aligned with all other
    /// arguments help text, it must be specified via a tag inside curly braces, like so `{n}`.
    /// Using the standard `\n` will produce a newline, but it will not be properly aligned.
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -461,7 +471,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Setting `help` displays a short message to the side of the argument when the user passes
    /// `-h` or `--help` (by default).
    ///
-    /// ```ignore
+    /// ```rust
    /// # use clap::{App, Arg};
    /// let m = App::new("helptest")
    ///     .arg(Arg::with_name("cfg")
@ -470,8 +480,6 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///     .get_matches_from(vec![
    ///         "shorttest", "--help"
    ///     ]);
    ///
    /// // ...
    /// ```
    ///
    /// The above example displays
@ -496,7 +504,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// required, when no other conflicting rules have been evaluated. Conflicting rules take
    /// precedence over being required. **Default:** `false`
    ///
-    /// **NOTE:** Flags (i.e. not positional, or arguments that take values) cannot be required.
+    /// **NOTE:** Flags (i.e. not positional, or arguments that take values) cannot be required by
    /// default. This is simply because if a flag should be required, it should simply be implied
    /// as no additional information is required from user. Flags by their very nature are simply
    /// yes/no, or true/false.
    ///
    /// # Examples
    ///
@ -507,7 +518,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// # ;
    /// ```
    ///
-    /// Setting `required(true)` requires that the argument be used at runtime.
+    /// Setting [`Arg::required(true)`] requires that the argument be used at runtime.
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -523,7 +534,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_ok());
    /// ```
    ///
-    /// Setting `required(true)` and *not* supplying that argument is an error.
+    /// Setting [`Arg::required(true)`] and *not* supplying that argument is an error.
    ///
    /// ```rust
    /// # use clap::{App, Arg, ErrorKind};
@ -539,6 +550,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
    /// ```
    /// [`Arg::required(true)`]: ./struct.Arg.html#method.required
    pub fn required(self, r: bool) -> Self {
        if r {
            self.set(ArgSettings::Required)
@ -550,7 +562,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Sets an arg that override this arg's required setting. (i.e. this arg will be required
    /// unless this other argument is present).
    ///
-    /// **Pro Tip:** Using `Arg::required_unless` implies `Arg::required` and is therefore not
+    /// **Pro Tip:** Using [`Arg::required_unless`] implies [`Arg::required`] and is therefore not
    /// mandatory to also set.
    ///
    /// # Examples
@ -562,9 +574,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// # ;
    /// ```
    ///
-    /// Setting `required_unless(name)` requires that the argument be used at runtime *unless*
+    /// Setting [`Arg::required_unless(name)`] requires that the argument be used at runtime
-    /// `name` is present. In the following example, the required argument is *not* provided, but
+    /// *unless* `name` is present. In the following example, the required argument is *not*
-    /// it's not an error because the `unless` arg has been supplied.
+    /// provided, but it's not an error because the `unless` arg has been supplied.
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -582,7 +594,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_ok());
    /// ```
    ///
-    /// Setting `required_unless(name)` and *not* supplying `name` or this arg is an error.
+    /// Setting [`Arg::required_unless(name)`] and *not* supplying `name` or this arg is an error.
    ///
    /// ```rust
    /// # use clap::{App, Arg, ErrorKind};
@ -600,6 +612,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
    /// ```
    /// [`Arg::required_unless`]: ./struct.Arg.html#method.required_unless
    /// [`Arg::required`]: ./struct.Arg.html#method.required
    /// [`Arg::required_unless(name)`]: ./struct.Arg.html#method.required_unless
    pub fn required_unless(mut self, name: &'a str) -> Self {
        if let Some(ref mut vec) = self.r_unless {
            vec.push(name);
@ -613,7 +628,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// all these other argument are present).
    ///
    /// **NOTE:** If you wish for the this argument to only be required if *one of* these args are
-    /// present see `Arg::required_unless_one`
+    /// present see [`Arg::required_unless_one`]
    ///
    /// # Examples
    ///
@ -624,9 +639,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// # ;
    /// ```
    ///
-    /// Setting `required_unless_all(names)` requires that the argument be used at runtime *unless*
+    /// Setting [`Arg::required_unless_all(names)`] requires that the argument be used at runtime
-    /// *all* the args in `names` are present. In the following example, the required argument is
+    /// *unless* *all* the args in `names` are present. In the following example, the required
-    /// *not* provided, but it's not an error because all the `unless` args have been supplied.
+    /// argument is *not* provided, but it's not an error because all the `unless` args have been
    /// supplied.
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -647,8 +663,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_ok());
    /// ```
    ///
-    /// Setting `required_unless_all(names)` and *not* supplying *all* of `names` or this arg is an
+    /// Setting [`Arg::required_unless_all(names)`] and *not* supplying *all* of `names` or this
-    /// error.
+    /// arg is an error.
    ///
    /// ```rust
    /// # use clap::{App, Arg, ErrorKind};
@ -669,6 +685,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
    /// ```
    /// [`Arg::required_unless_one`]: ./struct.Arg.html#method.required_unless_one
    /// [`Arg::required_unless_all(names)`]: ./struct.Arg.html#method.required_unless_all
    pub fn required_unless_all(mut self, names: &[&'a str]) -> Self {
        if let Some(ref mut vec) = self.r_unless {
            for s in names {
@ -681,11 +699,11 @@ impl<'a, 'b> Arg<'a, 'b> {
        self.required(true)
    }
-    /// Sets args that override this arg's required setting. (i.e. this arg will be required unless
+    /// Sets args that override this arg's [required] setting. (i.e. this arg will be required
-    /// *at least one of* these other argument are present).
+    /// unless *at least one of* these other argument are present).
    ///
    /// **NOTE:** If you wish for the this argument to only be required if *all of* these args are
-    /// present see `Arg::required_unless_all`
+    /// present see [`Arg::required_unless_all`]
    ///
    /// # Examples
    ///
@ -696,10 +714,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// # ;
    /// ```
    ///
-    /// Setting `required_unless_one(names)` requires that the argument be used at runtime *unless*
+    /// Setting [`Arg::required_unless_one(names)`] requires that the argument be used at runtime
-    /// *at least one of* the args in `names` are present. In the following example, the required
+    /// *unless* *at least one of* the args in `names` are present. In the following example, the
-    /// argument is *not* provided, but it's not an error because one the `unless` args have been
+    /// required argument is *not* provided, but it's not an error because one the `unless` args
-    /// supplied.
+    /// have been supplied.
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -720,8 +738,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_ok());
    /// ```
    ///
-    /// Setting `required_unless_one(names)` and *not* supplying *at least one of* `names` or this
+    /// Setting [`Arg::required_unless_one(names)`] and *not* supplying *at least one of* `names`
-    /// arg is an error.
+    /// or this arg is an error.
    ///
    /// ```rust
    /// # use clap::{App, Arg, ErrorKind};
@ -742,6 +760,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
    /// ```
    /// [required]: ./struct.Arg.html#method.required
    /// [`Arg::required_unless_one(names)`]: ./struct.Arg.html#method.required_unless_one
    /// [`Arg::required_unless_all`]: ./struct.Arg.html#method.required_unless_all
    pub fn required_unless_one(mut self, names: &[&'a str]) -> Self {
        if let Some(ref mut vec) = self.r_unless {
            for s in names {
@ -799,7 +820,7 @@ impl<'a, 'b> Arg<'a, 'b> {
        self
    }
-    /// The same as `Arg::conflicts_with` but allows specifying multiple two-way conlicts per
+    /// The same as [`Arg::conflicts_with`] but allows specifying multiple two-way conlicts per
    /// argument.
    ///
    /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
@ -839,6 +860,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
    /// ```
    /// [`Arg::conflicts_with`]: ./struct.Arg.html#method.conflicts_with
    pub fn conflicts_with_all(mut self, names: &[&'a str]) -> Self {
        if let Some(ref mut vec) = self.blacklist {
            for s in names {
@ -924,7 +946,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Sets an argument by name that is required when this one is present I.e. when
    /// using this argument, the following argument *must* be present.
    ///
-    /// **NOTE:** Conflicting rules and override rules take precedence over being required
+    /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
    ///
    /// # Examples
    ///
@ -935,8 +957,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// # ;
    /// ```
    ///
-    /// Setting `requires("arg")` requires that the argument be used at runtime if the defining
+    /// Setting [`Arg::requires(name)`] requires that the argument be used at runtime if the
-    /// argument is used. If the defining argument isn't used, the other arguemnt isn't required
+    /// defining argument is used. If the defining argument isn't used, the other arguemnt isn't
    /// required
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -954,7 +977,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_ok()); // We didn't use cfg, so input wasn't required
    /// ```
    ///
-    /// Setting `requires("arg")` and *not* supplying that argument is an error.
+    /// Setting [`Arg::requires(name)`] and *not* supplying that argument is an error.
    ///
    /// ```rust
    /// # use clap::{App, Arg, ErrorKind};
@ -972,6 +995,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
    /// ```
    /// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
    /// [override]: ./struct.Arg.html#method.overrides_with
    pub fn requires(mut self, name: &'a str) -> Self {
        if let Some(ref mut vec) = self.requires {
            vec.push(name);
@ -984,7 +1010,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Sets multiple arguments by names that are required when this one is present I.e. when
    /// using this argument, the following arguments *must* be present.
    ///
-    /// **NOTE:** Mutually exclusive and override rules take precedence over being required
+    /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
    /// by default.
    ///
    /// # Examples
@ -996,9 +1022,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// # ;
    /// ```
    ///
-    /// Setting `requires_all(&["arg", "arg2"])` requires that all the arguments be used at runtime
+    /// Setting [`Arg::requires_all(&[arg, arg2])`] requires that all the arguments be used at
-    /// if the defining argument is used. If the defining argument isn't used, the other arguemnt
+    /// runtime if the defining argument is used. If the defining argument isn't used, the other
-    /// isn't required
+    /// arguemnt isn't required
    ///
    /// ```rust
    /// # use clap::{App, Arg};
@ -1018,7 +1044,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_ok()); // We didn't use cfg, so input and output weren't required
    /// ```
    ///
-    /// Setting `requires_all(&["arg", "arg2"])` and *not* supplying all the arguments is an error.
+    /// Setting [`Arg::requires_all(&[arg, arg2])`] and *not* supplying all the arguments is an
    /// error.
    ///
    /// ```rust
    /// # use clap::{App, Arg, ErrorKind};
@ -1039,6 +1066,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// // We didn't use output
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
    /// ```
    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
    /// [override]: ./struct.Arg.html#method.overrides_with
    /// [`Arg::requires_all(&[arg, arg2])`]: ./struct.Arg.html#method.requires_all
    pub fn requires_all(mut self, names: &[&'a str]) -> Self {
        if let Some(ref mut vec) = self.requires {
            for s in names {
@ -1058,10 +1088,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// * Using an equals and no space such as `-o=value` or `--option=value`
    /// * Use a short and no space such as `-ovalue`
    ///
-    /// **NOTE:** By default, values are delimted by commas, meaning `--option=val1,val2,val3` is
+    /// **NOTE:** By default, args which allow [multiple values] are delimted by commas, meaning
-    /// is three values for the `--option` argument. If you wish to change the delimiter to another
+    /// `--option=val1,val2,val3` is is three values for the `--option` argument. If you wish to
-    /// character you can use `Arg::value_delimiter(char)`, alternatively you can delimiting values
+    /// change the delimiter to another character you can use [`Arg::value_delimiter(char)`],
-    /// **OFF** by using `Arg::use_delimiter(false)`
+    /// alternatively you can delimiting values **OFF** by using [`Arg::use_delimiter(false)`]
    ///
    /// # Examples
    ///
@ -1083,6 +1113,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(m.is_present("mode"));
    /// assert_eq!(m.value_of("mode"), Some("fast"));
    /// ```
    /// [`Arg::value_delimiter(char)`]: ./struct.Arg.html#method.value_delimiter
    /// [`Arg::use_delimiter(false)`]: ./struct.Arg.html#method.use_delimiter
    /// [multiple values]: ./struct.Arg.html#method.multiple
    pub fn takes_value(self, tv: bool) -> Self {
        if tv {
            self.set(ArgSettings::TakesValue)
@ -1096,18 +1129,18 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// **NOTE:** The index refers to position according to **other positional argument**. It does
    /// not define position in the argument list as a whole.
    ///
-    /// **NOTE:** If no `short`, or `long` have been defined, you can optionally leave off the
+    /// **NOTE:** If no [`Arg::short`], or [`Arg::long`] have been defined, you can optionally
-    /// `index` method, and the index will be assigned in order of evaluation. Utilizing the
+    /// leave off the `index` method, and the index will be assigned in order of evaluation.
-    /// `index` method allows for setting indexes out of order
+    /// Utilizing the `index` method allows for setting indexes out of order
    ///
-    /// **NOTE:** When utilized with `multiple(true)`, only the **last** psoitional argument may
+    /// **NOTE:** When utilized with [`Arg::multiple(true)`], only the **last** psoitional argument
-    /// be defined as multiple (i.e. with the highest index)
+    /// may be defined as multiple (i.e. with the highest index)
    ///
    /// # Panics
    ///
-    /// Although not in this method directly, `App` will `panic!` if indexes are skipped (such as
+    /// Although not in this method directly, [`App`] will [`panic!`] if indexes are skipped (such
-    /// defining `index(1)` and `index(3)` but not `index(2)`, or a positional argument is defined
+    /// as defining `index(1)` and `index(3)` but not `index(2)`, or a positional argument is
-    /// as multiple and is not the highest index
+    /// defined as multiple and is not the highest index
    ///
    /// # Examples
    ///
@ -1131,6 +1164,11 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert_eq!(m.value_of("mode"), Some("fast")); // notice index(1) means "first positional"
    ///                                               // *not* first argument
    /// ```
    /// [`Arg::short`]: ./struct.Arg.html#method.short
    /// [`Arg::long`]: ./struct.Arg.html#method.long
    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
    /// [`App`]: ./struct.App.html
    /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
    pub fn index(mut self, idx: u64) -> Self {
        self.index = Some(idx);
        self
@ -1146,18 +1184,18 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// **WARNING:**
    ///
-    /// Setting `multipe(true)` for an option allows multiple values **and** multiple occurrences
+    /// Setting `multiple(true)` for an [option] with no other details, allows multiple values
-    /// because it isn't possible to more occurrences than values for options. Because multiple
+    /// **and** multiple occurrences because it isn't possible to more occurrences than values for
-    /// values are allowed, `--option val1 val2 val3` is perfectly valid, be careful when designing
+    /// options. Because multiple values are allowed, `--option val1 val2 val3` is perfectly valid,
-    /// a CLI where positional arguments are expectd after a option which accepts multiple values,
+    /// be careful when designing a CLI where positional arguments are expectd after a option which
-    /// as `clap` will continue parsing *values* until it reaches the max or specific number of
+    /// accepts multiple values, as `clap` will continue parsing *values* until it reaches the max
-    /// values defined, or another flag or option.
+    /// or specific number of values defined, or another flag or option.
    ///
    /// **Pro Tip**:
    ///
    /// It's possible to define an option which allows multiple occurrences, but only one value per
-    /// occurrence. To do this use `Arg::number_of_values(1)` in coordination with
+    /// occurrence. To do this use [`Arg::number_of_values(1)`] in coordination with
-    /// `Arg::multiple(true)`.
+    /// [`Arg::multiple(true)`].
    ///
    /// # Examples
    ///
@ -1260,8 +1298,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(m.is_present("word"));
    /// assert_eq!(m.value_of("word"), Some("word"));
    /// ```
-    /// As a final example, notice if we define `number_of_values(1)` and try to run the problem
+    /// As a final example, notice if we define [`Arg::number_of_values(1)`] and try to run the
-    /// example above, it would have been a runtime error with a pretty message to the user :)
+    /// problem example above, it would have been a runtime error with a pretty message to the
    /// user :)
    ///
    /// ```rust
    /// # use clap::{App, Arg, ErrorKind};
@ -1278,6 +1317,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
    /// ```
    /// [option]: ./struct.Arg.html#method.takes_value
    /// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
    pub fn multiple(self, multi: bool) -> Self {
        if multi {
            self.set(ArgSettings::Multiple)
@ -1286,16 +1328,16 @@ impl<'a, 'b> Arg<'a, 'b> {
        }
    }
-    /// Specifies that an argument can be matched to all child subcommands.
+    /// Specifies that an argument can be matched to all child [`SubCommand`]s.
    ///
    /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands)
    ///
-    /// **NOTE:** Global arguments *cannot* be required.
+    /// **NOTE:** Global arguments *cannot* be [required].
    ///
    /// **NOTE:** Global arguments, when matched, *only* exist in the command's matches that they
    /// were matched to. For example, if you defined a `--flag` global argument in the top most
    /// parent command, but the user supplied the arguments `top cmd1 cmd2 --flag` *only* `cmd2`'s
-    /// `ArgMatches` would return `true` if tested for `.is_present("flag")`.
+    /// [`ArgMatches`] would return `true` if tested for [`ArgMatches::is_present("flag")`].
    ///
    /// # Examples
    ///
@ -1309,7 +1351,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// For example, assume an appliction with two subcommands, and you'd like to define a
    /// `--verbose` flag that can be called on any of the subcommands and parent, but you don't
-    /// want to clutter the source with three duplicate `Arg` definitions.
+    /// want to clutter the source with three duplicate [`Arg`] definitions.
    ///
    /// ```rust
    /// # use clap::{App, Arg, SubCommand};
@ -1326,6 +1368,11 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// let sub_m = m.subcommand_matches("do-stuff").unwrap();
    /// assert!(sub_m.is_present("verb"));
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [required]: ./struct.Arg.html#method.required
    /// [`ArgMatches`]: ./struct.ArgMatches.html
    /// [`ArgMatches::is_present("flag")`]: ./struct.ArgMatches.html#method.is_present
    /// [`Arg`]: ./struct.Arg.html
    pub fn global(self, g: bool) -> Self {
        if g {
            self.set(ArgSettings::Global)
@ -1339,7 +1386,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// **NOTE:** Defaults to `true` (Explicitly empty values are allowed)
    ///
-    /// **NOTE:** Implicitly sets `takes_value(true)` when set to `false`
+    /// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] when set to `false`
    ///
    /// # Examples
    ///
@ -1365,6 +1412,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
    /// ```
    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
    pub fn empty_values(mut self, ev: bool) -> Self {
        if ev {
            self.set(ArgSettings::EmptyValues)
@ -1388,7 +1436,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// ```
    /// Setting `hidden(true)` will hide the argument when displaying help text
    ///
-    /// ```ignore
+    /// ```rust
    /// # use clap::{App, Arg};
    /// let m = App::new("helptest")
    ///     .arg(Arg::with_name("cfg")
@ -1398,8 +1446,6 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///     .get_matches_from(vec![
    ///         "shorttest", "--help"
    ///     ]);
    ///
    /// // ...
    /// ```
    ///
    /// The above example displays
@ -1422,10 +1468,10 @@ impl<'a, 'b> Arg<'a, 'b> {
        }
    }
-    /// Specifies a list of possible values for this argument. At runtime, `clap` verifies that only
+    /// Specifies a list of possible values for this argument. At runtime, `clap` verifies that
-    /// one of the specified values was used, or fails with an error message.
+    /// only one of the specified values was used, or fails with an error message.
    ///
-    /// **NOTE:** This setting only applies to options and positional arguments
+    /// **NOTE:** This setting only applies to [options] and [positional arguments]
    ///
    /// # Examples
    ///
@ -1463,6 +1509,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
    /// ```
    /// [options]: ./struct.Arg.html#method.takes_value
    /// [positional arguments]: ./struct.Arg.html#method.index
    pub fn possible_values(mut self, names: &[&'b str]) -> Self {
        if let Some(ref mut vec) = self.possible_vals {
            for s in names {
@ -1477,6 +1525,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Specifies a possible value for this argument, one at a time. At runtime, `clap` verifies
    /// that only one of the specified values was used, or fails with error message.
    ///
    /// **NOTE:** This setting only applies to [options] and [positional arguments]
    ///
    /// # Examples
    ///
    /// ```rust
@ -1519,6 +1569,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
    /// ```
    /// [options]: ./struct.Arg.html#method.takes_value
    /// [positional arguments]: ./struct.Arg.html#method.index
    pub fn possible_value(mut self, name: &'b str) -> Self {
        if let Some(ref mut vec) = self.possible_vals {
            vec.push(name);
@ -1528,7 +1580,7 @@ impl<'a, 'b> Arg<'a, 'b> {
        self
    }
-    /// Specifies the name of the group the argument belongs to.
+    /// Specifies the name of the [`ArgGroup`] the argument belongs to.
    ///
    /// # Examples
    ///
@ -1555,6 +1607,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///     .get_matches_from(vec!["posvals", "--debug"]);
    /// assert!(m.is_present("mode"));
    /// ```
    /// [`ArgGroup`]: ./struct.ArgGroup.html
    pub fn group(mut self, name: &'a str) -> Self {
        self.group = Some(name);
        self
@ -1565,9 +1618,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// `.number_of_values(3)`, and this argument wouldn't be satisfied unless the user provided
    /// 3 and only 3 values.
    ///
-    /// **NOTE:** Does *not* require `.multiple(true)` to be set. Setting `.multiple(true)` would
+    /// **NOTE:** Does *not* require [`Arg::multiple(true)`] to be set. Setting
-    /// allow `-f <file> <file> <file> -f <file> <file> <file>` where as *not* setting
+    /// [`Arg::multiple(true)`] would allow `-f <file> <file> <file> -f <file> <file> <file>` where
-    /// `.multiple(true)` would only allow one occurrence of this argument.
+    /// as *not* setting [`Arg::multiple(true)`] would only allow one occurrence of this argument.
    ///
    /// # Examples
    ///
@ -1593,22 +1646,23 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues);
    /// ```
    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
    pub fn number_of_values(mut self, qty: u64) -> Self {
        self.num_vals = Some(qty);
        self
    }
-    /// Allows one to perform a custom validation on the argument value. You provide a closure which
+    /// Allows one to perform a custom validation on the argument value. You provide a closure
-    /// accepts a `String` value, a `Result` where the `Err(String)` is a message displayed to the
+    /// which accepts a [`String`] value, and return a [`Result`] where the [`Err(String)`] is a
-    /// user.
+    /// message displayed to the user.
    ///
    /// **NOTE:** The error message does *not* need to contain the `error:` portion, only the
    /// message.
    ///
    /// **NOTE:** There is a small performance hit for using validators, as they are implemented
-    /// with `Rc` pointers. And the value to be checked will be allocated an extra time in order to
+    /// with [`Rc`] pointers. And the value to be checked will be allocated an extra time in order
-    /// to be passed to the closure. This performance hit is extremely minimal in the grand scheme
+    /// to to be passed to the closure. This performance hit is extremely minimal in the grand
-    /// of things.
+    /// scheme of things.
    ///
    /// # Examples
    ///
@ -1628,6 +1682,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_ok());
    /// assert_eq!(res.unwrap().value_of("file"), Some("some@file"));
    /// ```
    /// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
    /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
    /// [`Err(String)`]: https://doc.rust-lang.org/std/result/enum.Result.html#variant.Err
    /// [`Rc`]: https://doc.rust-lang.org/std/rc/struct.Rc.html
    pub fn validator<F>(mut self, f: F) -> Self
        where F: Fn(String) -> Result<(), String> + 'static
    {
@ -1636,14 +1694,14 @@ impl<'a, 'b> Arg<'a, 'b> {
    }
    /// Specifies the *maximum* number of values are for this argument. For example, if you had a
-    /// `-f <file>` argument where you wanted up to 3 'files' you would set
+    /// `-f <file>` argument where you wanted up to 3 'files' you would set `.max_values(3)`, and
-    /// `.max_values(3)`, and this argument would be satisfied if the user provided, 1, 2, or 3
+    /// this argument would be satisfied if the user provided, 1, 2, or 3 values.
    /// values.
    ///
-    /// **NOTE:** This does not implicitly set `mulitple(true)`. This is because `-o val -o val` is
+    /// **NOTE:** This does *not* implicitly set [`Arg::mulitple(true)`]. This is because
-    /// multiples occurrences but a single value and `-o val1 val2` is a single occurence with
+    /// `-o val -o val` is multiples occurrences but a single value and `-o val1 val2` is a single
-    /// multple values. For positional arguments this **does** set `multiple(true)` because there
+    /// occurence with multple values. For positional arguments this **does** set
-    /// is no way to determine the diffrence between multiple occureces and multiple values.
+    /// [`Arg::multiple(true)`] because there is no way to determine the diffrence between multiple
    /// occureces and multiple values.
    ///
    /// # Examples
    ///
@ -1686,6 +1744,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::TooManyValues);
    /// ```
    /// [`Arg::mulitple(true)`]: ./struct.Arg.html#method.multiple
    pub fn max_values(mut self, qty: u64) -> Self {
        self.max_vals = Some(qty);
        self
@ -1696,10 +1755,11 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// `.min_values(2)`, and this argument would be satisfied if the user provided, 2 or more
    /// values.
    ///
-    /// **NOTE:** This does not implicitly set `mulitple(true)`. This is because `-o val -o val` is
+    /// **NOTE:** This does not implicitly set [`Arg::mulitple(true)`]. This is because
-    /// multiples occurrences but a single value and `-o val1 val2` is a single occurence with
+    /// `-o val -o val` is multiples occurrences but a single value and `-o val1 val2` is a single
-    /// multple values. For positional arguments this **does** set `multiple(true)` because there
+    /// occurence with multple values. For positional arguments this **does** set
-    /// is no way to determine the diffrence between multiple occureces and multiple values.
+    /// [`Arg::multiple(true)`] because there is no way to determine the diffrence between multiple
    /// occureces and multiple values.
    ///
    /// # Examples
    ///
@ -1742,6 +1802,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::TooFewValues);
    /// ```
    /// [`Arg::mulitple(true)`]: ./struct.Arg.html#method.multiple
    pub fn min_values(mut self, qty: u64) -> Self {
        self.min_vals = Some(qty);
        self.set(ArgSettings::TakesValue)
@ -1753,7 +1814,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// value delimiter for all arguments that accept values (options and positional arguments)
    ///
    /// **NOTE:** The defalt is `true`. Setting the value to `true` will reset any previous use of
-    /// `Arg::value_delimiter` back to the default of `,` (comma).
+    /// [`Arg::value_delimiter`] back to the default of `,` (comma).
    ///
    /// # Examples
    ///
@ -1792,6 +1853,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert_eq!(nodelims.occurrences_of("option"), 1);
    /// assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");
    /// ```
    /// [`Arg::value_delimiter`]: ./struct.Arg.html#method.value_delimiter
    pub fn use_delimiter(mut self, d: bool) -> Self {
        if d {
            self.val_delim = Some(',');
@ -1804,9 +1866,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Specifies the separator to use when values are clumped together, defaults to `,` (comma).
    ///
-    /// **NOTE:** implicitly sets `Arg::use_delimiter(true)`
+    /// **NOTE:** implicitly sets [`Arg::use_delimiter(true)`]
    ///
-    /// **NOTE:** implicitly sets `Arg::takes_value(true)`
+    /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
    ///
    /// # Examples
    ///
@ -1824,6 +1886,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// assert_eq!(m.values_of("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])
    /// ```
    /// [`Arg::use_delimiter(true)`]: ./struct.Arg.html#method.use_delimiter
    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
    pub fn value_delimiter(mut self, d: &str) -> Self {
        self = self.set(ArgSettings::TakesValue);
        self = self.set(ArgSettings::UseValueDelimiter);
@ -1842,16 +1906,16 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
    /// use all capital letters for the value name.
    ///
-    /// **Pro Tip:** It may help to use `Arg::next_line_help(true)` if there are long, or multiple
+    /// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or
-    /// value names in order to not throw off the help text alignment of all options.
+    /// multiple value names in order to not throw off the help text alignment of all options.
    ///
-    /// **NOTE:** This implicitly sets `.number_of_values()` if the number of value names is
+    /// **NOTE:** This implicitly sets [`Arg::number_of_values`] if the number of value names is
    /// greater than one. I.e. be aware that the number of "names" you set for the values, will be
    /// the *exact* number of values required to satisfy this argument
    ///
-    /// **NOTE:** implicitly sets `Arg::takes_value(true)`
+    /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
    ///
-    /// **NOTE:** Does *not* require or imply `.multiple(true)`.
+    /// **NOTE:** Does *not* require or imply [`Arg::multiple(true)`].
    ///
    /// # Examples
    ///
@ -1888,6 +1952,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// OPTIONS:
    ///     --io-files <INFILE> <OUTFILE>    Some help text
    /// ```
    /// [`Arg::next_line_help(true)`]: ./struct.Arg.html#method.next_line_help
    /// [`Arg::number_of_values`]: ./struct.Arg.html#method.number_of_values
    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
    pub fn value_names(mut self, names: &[&'b str]) -> Self {
        self.setb(ArgSettings::TakesValue);
        if let Some(ref mut vals) = self.val_names {
@ -1906,13 +1974,13 @@ impl<'a, 'b> Arg<'a, 'b> {
        self
    }
-    /// Specifies the name for value of option or positional arguments inside of help documenation.
+    /// Specifies the name for value of [option] or [positional] arguments inside of help
-    /// This name is cosmetic only, the name is **not** used to access arguments. This setting can
+    /// documenation. This name is cosmetic only, the name is **not** used to access arguments.
-    /// be very helpful when describing the type of input the user should be using, such as `FILE`,
+    /// This setting can be very helpful when describing the type of input the user should be
-    /// `INTERFACE`, etc. Although not required, it's somewhat convention to use all capital
+    /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
-    /// letters for the value name.
+    /// use all capital letters for the value name.
    ///
-    /// **NOTE:** implicitly sets `Arg::takes_value(true)`
+    /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
    ///
    /// # Examples
    ///
@ -1949,6 +2017,9 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// OPTIONS:
    ///     --config <FILE>     Some help text
    /// ```
    /// [option]: ./struct.Arg.html#method.takes_value
    /// [positional]: ./struct.Arg.html#method.index
    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
    pub fn value_name(mut self, name: &'b str) -> Self {
        self.setb(ArgSettings::TakesValue);
        if let Some(ref mut vals) = self.val_names {
@ -1964,15 +2035,15 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// Specifies the value of the argument when *not* specified at runtime.
    ///
-    /// **NOTE:** If the user *does not* use this argument at runtime, `ArgMatches::occurrences_of`
+    /// **NOTE:** If the user *does not* use this argument at runtime, [`ArgMatches::occurrences_of`]
-    /// will return `0` even though the `value_of` will return the default specified.
+    /// will return `0` even though the [`ArgMatches::value_of`] will return the default specified.
    ///
-    /// **NOTE:** If the user *does not* use this argument at runtime `ArgMatches::is_present` will
+    /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::is_present`] will
    /// still return `true`. If you wish to determine whether the argument was used at runtime or
-    /// not, consider `ArgMatches::occurrences_of` which will return `0` if the argument was *not*
+    /// not, consider [`ArgMatches::occurrences_of`] which will return `0` if the argument was *not*
    /// used at runtmie.
    ///
-    /// **NOTE:** This implicitly sets `Arg::takes_value(true)`.
+    /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
    ///
    /// # Examples
    ///
@ -1990,6 +2061,10 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// assert!(m.is_present("opt"));
    /// assert_eq!(m.occurrences_of("opt"), 0);
    /// ```
    /// [`ArgMatches::occurrences_of`]: /struct.ArgMatches.html#method.occurrences_of
    /// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
    /// [`Arg::takes_value(true)`]: /struct.Arg.html#method.takes_value
    /// [`ArgMatches::is_present`]: /struct.ArgMatches.html#method.is_present
    pub fn default_value(mut self, val: &'a str) -> Self {
        self.setb(ArgSettings::TakesValue);
        self.default_val = Some(val);
@ -2000,7 +2075,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    /// indented once. This can be helpful for arguments with very long or complex help messages.
    /// 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`
+    /// **NOTE:** To apply this setting to all arguments consider using
    /// [`AppSettings::NextLineHelp`]
    ///
    /// # Examples
    ///
@ -2023,7 +2099,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// The above example displays the following help message
    ///
-    /// ```ignore
+    /// ```notrust
    /// nlh
    ///
    /// USAGE:
@ -2039,6 +2115,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///         help that makes more sense to be
    ///         on a line after the option
    /// ```
    /// [`AppSettings::NextLineHelp`]: ./enum.AppSettings.html#variant.NextLineHelp
    pub fn next_line_help(mut self, nlh: bool) -> Self {
        if nlh {
            self.setb(ArgSettings::NextLineHelp);
@ -2056,8 +2133,8 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// **NOTE:** The default is 999 for all arguments.
    ///
-    /// **NOTE:** This setting is ignored for positional arguments which are always displayed in
+    /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in
-    /// index order.
+    /// [index] order.
    ///
    /// # Examples
    ///
@ -2087,7 +2164,7 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///
    /// The above example displays the following help message
    ///
-    /// ```ignore
+    /// ```notrust
    /// cust-ord
    ///
    /// USAGE:
@ -2101,23 +2178,28 @@ impl<'a, 'b> Arg<'a, 'b> {
    ///     -O, --other-option <b>    I should be first!
    ///     -o, --long-option <a>     Some help and text
    /// ```
    /// [positional arguments]: ./struct.Arg.html#method.index
    /// [index]: ./struct.Arg.html#method.index
    pub fn display_order(mut self, ord: usize) -> Self {
        self.disp_ord = ord;
        self
    }
-    /// Checks if one of the `ArgSettings` settings is set for the argument
+    /// Checks if one of the [`ArgSettings`] settings is set for the argument
    /// [`ArgSettings`]: ./enum.ArgSettings.html
    pub fn is_set(&self, s: ArgSettings) -> bool {
        self.settings.is_set(s)
    }
-    /// Sets one of the `ArgSettings` settings for the argument
+    /// Sets one of the [`ArgSettings`] settings for the argument
    /// [`ArgSettings`]: ./enum.ArgSettings.html
    pub fn set(mut self, s: ArgSettings) -> Self {
        self.setb(s);
        self
    }
-    /// Unsets one of the `ArgSettings` settings for the argument
+    /// Unsets one of the [`ArgSettings`] settings for the argument
    /// [`ArgSettings`]: ./enum.ArgSettings.html
    pub fn unset(mut self, s: ArgSettings) -> Self {
        self.unsetb(s);
        self
--- a/src/args/arg_matches.rs
+++ b/src/args/arg_matches.rs
@ -11,7 +11,7 @@ use args::MatchedArg;
 use INVALID_UTF8;
 /// Used to get information about the arguments that where supplied to the program at runtime by
-/// the user. New instances of this struct are obtained by using the `App::get_matches` family of
+/// the user. New instances of this struct are obtained by using the [`App::get_matches`] family of
 /// methods.
 ///
 /// # Examples
@ -56,6 +56,7 @@ use INVALID_UTF8;
 ///     }
 /// }
 /// ```
 /// [`App::get_matches`]: ./struct.App.html#method.get_matches
 #[derive(Debug, Clone)]
 pub struct ArgMatches<'a> {
    #[doc(hidden)]
@ -82,16 +83,17 @@ impl<'a> ArgMatches<'a> {
        ArgMatches { ..Default::default() }
    }
-    /// Gets the value of a specific option or positional argument (i.e. an argument that takes
+    /// Gets the value of a specific [option] or [positional] argument (i.e. an argument that takes
    /// an additional value at runtime). If the option wasn't present at runtime
    /// it returns `None`.
    ///
    /// *NOTE:* If getting a value for an option or positional argument that allows multiples,
-    /// prefer `values_of()` as `value_of()` will only return the *first* value.
+    /// prefer [`ArgMatches::values_of`] as `ArgMatches::value_of` will only return the *first*
    /// value.
    ///
    /// # Panics
    ///
-    /// This method will `panic!` if the value contains invalid UTF-8 code points.
+    /// This method will [`panic!`] if the value contains invalid UTF-8 code points.
    ///
    /// # Examples
    ///
@ -104,6 +106,10 @@ impl<'a> ArgMatches<'a> {
    ///
    /// assert_eq!(m.value_of("output"), Some("something"));
    /// ```
    /// [option]: ./struct.Arg.html#method.takes_value
    /// [positional]: ./struct.Arg.html#method.index
    /// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of
    /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
    pub fn value_of<S: AsRef<str>>(&self, name: S) -> Option<&str> {
        if let Some(ref arg) = self.args.get(name.as_ref()) {
            if let Some(v) = arg.vals.values().nth(0) {
@ -118,7 +124,7 @@ impl<'a> ArgMatches<'a> {
    /// invalid points will be replaced with `\u{FFFD}`
    ///
    /// *NOTE:* If getting a value for an option or positional argument that allows multiples,
-    /// prefer `values_of_lossy()` as `value_of_lossy()` will only return the *first* value.
+    /// prefer [`Arg::values_of_lossy`] as `value_of_lossy()` will only return the *first* value.
    ///
    /// # Examples
    ///
@ -134,6 +140,7 @@ impl<'a> ArgMatches<'a> {
    ///                             OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
    /// assert_eq!(&*m.value_of_lossy("arg").unwrap(), "Hi \u{FFFD}!");
    /// ```
    /// [`Arg::values_of_lossy`]: ./struct.ArgMatches.html#method.values_of_lossy
    pub fn value_of_lossy<S: AsRef<str>>(&'a self, name: S) -> Option<Cow<'a, str>> {
        if let Some(arg) = self.args.get(name.as_ref()) {
            if let Some(v) = arg.vals.values().nth(0) {
@ -145,12 +152,13 @@ impl<'a> ArgMatches<'a> {
    /// Gets the OS version of a string value of a specific argument. If the option wasn't present
    /// at runtime it returns `None`. An OS value on Unix-like systems is any series of bytes,
-    /// regardless of whether or not they contain valid UTF-8 code points. Since `String`s in Rust
+    /// regardless of whether or not they contain valid UTF-8 code points. Since [`String`]s in
-    /// are guaranteed to be valid UTF-8, a valid filename on a Unix system as an argument value may
+    /// Rust are guaranteed to be valid UTF-8, a valid filename on a Unix system as an argument
-    /// contain invalid UTF-8 code points.
+    /// value may contain invalid UTF-8 code points.
    ///
    /// *NOTE:* If getting a value for an option or positional argument that allows multiples,
-    /// prefer `values_of_os()` as `value_of_os()` will only return the *first* value.
+    /// prefer [`ArgMatches::values_of_os`] as `Arg::value_of_os` will only return the *first*
    /// value.
    ///
    /// # Examples
    ///
@ -166,14 +174,17 @@ impl<'a> ArgMatches<'a> {
    ///                             OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
    /// assert_eq!(&*m.value_of_os("arg").unwrap().as_bytes(), [b'H', b'i', b' ', 0xe9, b'!']);
    /// ```
    /// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
    /// [`ArgMatches::values_of_os`]: ./struct.ArgMatches.html#method.values_of_os
    pub fn value_of_os<S: AsRef<str>>(&self, name: S) -> Option<&OsStr> {
        self.args
            .get(name.as_ref())
            .map_or(None, |arg| arg.vals.values().nth(0).map(|v| v.as_os_str()))
    }
-    /// Gets an Iterator of values of a specific argument (i.e. an argument that takes multiple
+    /// Gets a [`Values`] struct which implements [`Iterator`] for values of a specific argument
-    /// values at runtime). If the option wasn't present at runtime it returns `None`
+    /// (i.e. an argument that takes multiple values at runtime). If the option wasn't present at
    /// runtime it returns `None`
    ///
    /// # Panics
    ///
@ -194,6 +205,8 @@ impl<'a> ArgMatches<'a> {
    /// let vals: Vec<&str> = m.values_of("output").unwrap().collect();
    /// assert_eq!(vals, ["val1", "val2", "val3"]);
    /// ```
    /// [`Values`]: ./struct.Values.html
    /// [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
    pub fn values_of<S: AsRef<str>>(&'a self, name: S) -> Option<Values<'a>> {
        if let Some(ref arg) = self.args.get(name.as_ref()) {
            fn to_str_slice(o: &OsString) -> &str {
@ -205,9 +218,9 @@ impl<'a> ArgMatches<'a> {
        None
    }
-    /// Gets the lossy values of a specific argument If the option wasn't present at runtime
+    /// Gets the lossy values of a specific argument. If the option wasn't present at runtime
-    /// it returns `None`. A lossy value is one which contains invalid UTF-8 code points, those
+    /// it returns `None`. A lossy value is one where if it contains invalid UTF-8 code points,
-    /// invalid points will be replaced with `\u{FFFD}`
+    /// those invalid points will be replaced with `\u{FFFD}`
    ///
    /// # Examples
    ///
@ -236,11 +249,11 @@ impl<'a> ArgMatches<'a> {
        None
    }
-    /// Gets the OS version of a string value of a specific argument If the option wasn't present
+    /// Gets a [`OsValues`] struct which is implements [`Iterator`] for [`OsString`] values of a
-    /// at runtime it returns `None`. An OS value on Unix-like systems is any series of bytes,
+    /// specific argument. If the option wasn't present at runtime it returns `None`. An OS value
-    /// regardless of whether or not they contain valid UTF-8 code points. Since `String`s in Rust
+    /// on Unix-like systems is any series of bytes, regardless of whether or not they contain
-    /// are guaranteed to be valid UTF-8, a valid filename as an argument value on Linux (for
+    /// valid UTF-8 code points. Since [`String`]s in Rust are guaranteed to be valid UTF-8, a valid
-    /// example) may contain invalid UTF-8 code points.
+    /// filename as an argument value on Linux (for example) may contain invalid UTF-8 code points.
    ///
    /// # Examples
    ///
@ -262,6 +275,10 @@ impl<'a> ArgMatches<'a> {
    /// assert_eq!(itr.next(), Some(&*OsString::from_vec(vec![0xe9, b'!'])));
    /// assert_eq!(itr.next(), None);
    /// ```
    /// [`OsValues`]: ./struct.OsValues.html
    /// [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
    /// [`OsString`]: https://doc.rust-lang.org/std/ffi/struct.OsString.html
    /// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
    pub fn values_of_os<S: AsRef<str>>(&'a self, name: S) -> Option<OsValues<'a>> {
        fn to_str_slice(o: &OsString) -> &OsStr {
            &*o
@ -301,7 +318,8 @@ impl<'a> ArgMatches<'a> {
    /// it will return `0`.
    ///
    /// **NOTE:** This returns the number of times the argument was used, *not* the number of
-    /// values. For example, `-o val1 val2 val3 -o val4` would return `2`.
+    /// values. For example, `-o val1 val2 val3 -o val4` would return `2` (2 occurrences, but 4
    /// values).
    ///
    /// # Examples
    ///
@ -339,9 +357,9 @@ impl<'a> ArgMatches<'a> {
        self.args.get(name.as_ref()).map_or(0, |a| a.occurs)
    }
-    /// Because subcommands are essentially "sub-apps" they have their own `ArgMatches` as well.
+    /// Because [`Subcommand`]s are essentially "sub-[`App`]s" they have their own [`ArgMatches`]
-    /// This method returns the `ArgMatches` for a particular subcommand or None if the subcommand
+    /// as well. This method returns the [`ArgMatches`] for a particular subcommand or `None` if
-    /// wasn't present at runtime.
+    /// the subcommand wasn't present at runtime.
    ///
    /// # Examples
    ///
@ -367,6 +385,9 @@ impl<'a> ArgMatches<'a> {
    ///     assert_eq!(sub_m.value_of("opt"), Some("val"));
    /// }
    /// ```
    /// [`Subcommand`]: ./struct.SubCommand.html
    /// [`App`]: ./struct.App.html
    /// [`ArgMatches`]: ./struct.ArgMatches.html
    pub fn subcommand_matches<S: AsRef<str>>(&self, name: S) -> Option<&ArgMatches<'a>> {
        if let Some(ref s) = self.subcommand {
            if s.name == name.as_ref() {
@ -376,10 +397,10 @@ impl<'a> ArgMatches<'a> {
        None
    }
-    /// Because subcommands are essentially "sub-apps" they have their own `ArgMatches` as well.
+    /// Because [`Subcommand`]s are essentially "sub-[`App`]s" they have their own [`ArgMatches`]
-    /// But simply getting the sub-`ArgMatches` doesn't help much if we don't also know which
+    /// as well.But simply getting the sub-[`ArgMatches`] doesn't help much if we don't also know
-    /// subcommand was actually used. This method returns the name of the subcommand that was used
+    /// which subcommand was actually used. This method returns the name of the subcommand that was
-    /// at runtime, or `None` if one wasn't.
+    /// used at runtime, or `None` if one wasn't.
    ///
    /// *NOTE*: Subcommands form a hierarchy, where multiple subcommands can be used at runtime,
    /// but only a single subcommand from any group of sibling commands may used at once.
@ -431,12 +452,15 @@ impl<'a> ArgMatches<'a> {
    ///     _              => {}, // Either no subcommand or one not tested for...
    /// }
    /// ```
    /// [`Subcommand`]: ./struct.SubCommand.html
    /// [`App`]: ./struct.App.html
    /// [`ArgMatches`]: ./struct.ArgMatches.html
    pub fn subcommand_name(&self) -> Option<&str> {
        self.subcommand.as_ref().map(|sc| &sc.name[..])
    }
-    /// This brings together `ArgMatches::subcommand_matches` and `ArgMatches::subcommand_name` by
+    /// This brings together [`ArgMatches::subcommand_matches`] and [`ArgMatches::subcommand_name`]
-    /// returning a tuple with both pieces of information.
+    /// by returning a tuple with both pieces of information.
    ///
    /// # Examples
    ///
@ -479,11 +503,13 @@ impl<'a> ArgMatches<'a> {
    ///     _ => {},
    /// }
    /// ```
    /// [`ArgMatches::subcommand_matches`]: ./struct.ArgMatches.html#method.subcommand_matches
    /// [`ArgMatches::subcommand_name`]: ./struct.ArgMatches.html#method.subcommand_name
    pub fn subcommand(&self) -> (&str, Option<&ArgMatches<'a>>) {
        self.subcommand.as_ref().map_or(("", None), |sc| (&sc.name[..], Some(&sc.matches)))
    }
-    /// Returns a string slice of the usage statement for the `App` (or `SubCommand`)
+    /// Returns a string slice of the usage statement for the [`App`] or [`SubCommand`]
    ///
    /// # Examples
    ///
@ -495,6 +521,8 @@ impl<'a> ArgMatches<'a> {
    ///
    /// println!("{}", app_m.usage());
    /// ```
    /// [`Subcommand`]: ./struct.SubCommand.html
    /// [`App`]: ./struct.App.html
    pub fn usage(&self) -> &str {
        self.usage.as_ref().map_or("", |u| &u[..])
    }
@ -506,7 +534,8 @@ impl<'a> ArgMatches<'a> {
 // commit: be5e1fa3c26e351761b33010ddbdaf5f05dbcc33
 // license: MIT - Copyright (c) 2015 The Rust Project Developers
-/// An iterator for getting multiple values out of an argument via the `Arg::values_of` method.
+/// An iterator for getting multiple values out of an argument via the [`ArgMatches::values_of`]
 /// method.
 ///
 /// # Examples
 ///
@ -519,6 +548,7 @@ impl<'a> ArgMatches<'a> {
 ///
 /// assert_eq!(m.value_of("output"), Some("something"));
 /// ```
 /// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of
 #[derive(Clone)]
 #[allow(missing_debug_implementations)]
 pub struct Values<'a> {
@ -589,8 +619,9 @@ impl<'a, V> DoubleEndedIterator for Iter<'a, V> {
    }
 }
-/// An iterator for getting multiple values out of an argument via the `Arg::values_of_os` method.
+/// An iterator for getting multiple values out of an argument via the [`ArgMatches::values_of_os`]
-/// Usage of this iterator allows values which contain invalid UTF-8 code points unlike `Values`.
+/// method. Usage of this iterator allows values which contain invalid UTF-8 code points unlike
 /// [`Values`].
 ///
 /// # Examples
 ///
@ -606,6 +637,8 @@ impl<'a, V> DoubleEndedIterator for Iter<'a, V> {
 ///                             OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
 /// assert_eq!(&*m.value_of_os("arg").unwrap().as_bytes(), [b'H', b'i', b' ', 0xe9, b'!']);
 /// ```
 /// [`ArgMatches::values_of_os`]: ./struct.ArgMatches.html#method.values_of_os
 /// [`Values`]: ./struct.Values.html
 #[derive(Clone)]
 #[allow(missing_debug_implementations)]
 pub struct OsValues<'a> {
--- a/src/args/group.rs
+++ b/src/args/group.rs
@ -98,7 +98,7 @@ impl<'a> ArgGroup<'a> {
        ArgGroup::from(y.as_hash().unwrap())
    }
-    /// Adds an argument to this group by name
+    /// Adds an [argument] to this group by name
    ///
    /// # Examples
    ///
@ -110,6 +110,7 @@ impl<'a> ArgGroup<'a> {
    ///     .arg("config")
    /// # ;
    /// ```
    /// [argument]: ./struct.Arg.html
    pub fn arg(mut self, n: &'a str) -> Self {
        assert!(self.name != n,
                "ArgGroup '{}' can not have same name as arg inside it",
@ -118,7 +119,7 @@ impl<'a> ArgGroup<'a> {
        self
    }
-    /// Adds multiple arguments to this group by name
+    /// Adds multiple [arguments] to this group by name
    ///
    /// # Examples
    ///
@ -131,6 +132,7 @@ impl<'a> ArgGroup<'a> {
    ///     .args(&["config", "input"])
    /// # ;
    /// ```
    /// [arguments]: ./struct.Arg.html
    pub fn args(mut self, ns: &[&'a str]) -> Self {
        for n in ns {
            self = self.arg(n);
@ -143,7 +145,8 @@ impl<'a> ArgGroup<'a> {
    /// that one, and only one argument from this group *must* be present at runtime (unless
    /// conflicting with another argument).
    ///
-    /// **NOTE:** This setting only applies to the current `App` / `SubCommand`, and not globally.
+    /// **NOTE:** This setting only applies to the current [`App`] / [`SubCommand`], and not
    /// globally.
    ///
    /// # Examples
    ///
@ -157,6 +160,8 @@ impl<'a> ArgGroup<'a> {
    ///     .required(true)
    /// # ;
    /// ```
    /// [`App`]: ./struct.App.html
    /// [`SubCommand`]: ./struct.SubCommand.html
    pub fn required(mut self, r: bool) -> Self {
        self.required = r;
        self
--- a/src/args/settings.rs
+++ b/src/args/settings.rs
@ -44,7 +44,10 @@ impl Default for ArgFlags {
 }
 /// Various settings that apply to arguments and may be set, unset, and checked via getter/setter
-/// methods `Arg::set`, `Arg::unset`, and `Arg::is_set`
+/// methods [`Arg::set`], [`Arg::unset`], and [`Arg::is_set`]
 /// [`Arg::set`]: ./struct.Arg.html#method.set
 /// [`Arg::unset`]: ./struct.Arg.html#method.unset
 /// [`Arg::is_set`]: ./struct.Arg.html#method.is_set
 #[derive(Debug, PartialEq, Copy, Clone)]
 pub enum ArgSettings {
    /// The argument must be used
@ -53,7 +56,8 @@ pub enum ArgSettings {
    Multiple,
    /// The argument allows empty values such as `--option ""`
    EmptyValues,
-    /// The argument should be propagated down through all child subcommands
+    /// The argument should be propagated down through all child [`SubCommands`]
    /// [`SubCommand`]: ./struct.SubCommand.html
    Global,
    /// The argument should **not** be shown in help text
    Hidden,
--- a/src/args/subcommand.rs
+++ b/src/args/subcommand.rs
@ -7,8 +7,8 @@ use ArgMatches;
 /// The abstract representation of a command line subcommand.
 ///
 /// This struct describes all the valid options of the subcommand for the program. Subcommands are
-/// essentially "sub apps" and contain all the same possibilities (such as their own arguments,
+/// essentially "sub-[`App`]s" and contain all the same possibilities (such as their own
-/// subcommands, and settings).
+/// [arguments], subcommands, and settings).
 ///
 /// # Examples
 ///
@ -23,6 +23,8 @@ use ArgMatches;
 ///                 .index(1)))
 /// # ;
 /// ```
 /// [`App`]: ./struct.App.html
 /// [arguments]: ./struct.Arg.html
 #[derive(Debug, Clone)]
 pub struct SubCommand<'a> {
    #[doc(hidden)]
--- a/src/errors.rs
+++ b/src/errors.rs
@ -10,13 +10,14 @@ use fmt::Format;
 use suggestions;
 use args::any_arg::AnyArg;
-/// Short hand for result type
+/// Short hand for [`Result`] type
 /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
 pub type Result<T> = StdResult<T, Error>;
 /// Command line argument parser kind of error
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub enum ErrorKind {
-    /// Occurs when an `Arg` has a set of possible values, and the user provides a value which
+    /// Occurs when an [`Arg`] has a set of possible values, and the user provides a value which
    /// isn't in that set.
    ///
    /// # Examples
@ -31,6 +32,7 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidValue);
    /// ```
    /// [`Arg`]: ./struct.Arg.html
    InvalidValue,
    /// Occurs when a user provides a flag, option, or argument which wasn't defined.
    ///
@ -45,9 +47,9 @@ pub enum ErrorKind {
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::UnknownArgument);
    /// ```
    UnknownArgument,
-    /// Occurs when the user provids an unrecognized subcommand which meets the threshold for being
+    /// Occurs when the user provids an unrecognized [`SubCommand`] which meets the threshold for
-    /// similar enough to an existing subcommand so as to not cause the more general
+    /// being similar enough to an existing subcommand so as to not cause the more general
-    /// `UnknownArgument` error.
+    /// [`UnknownArgument`] error.
    ///
    /// # Examples
    ///
@ -63,13 +65,15 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidSubcommand);
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
    InvalidSubcommand,
-    /// Occurs when the user provids an unrecognized subcommand which does not meet the threshold
+    /// Occurs when the user provids an unrecognized [`SubCommand`] which does not meet the
-    /// for being similar enough to an existing subcommand so as to not cause the more detailed
+    /// threshold for being similar enough to an existing subcommand so as to not cause the more
-    /// `InvalidSubcommand` error.
+    /// detailed [`InvalidSubcommand`] error.
    ///
    /// This error typically happens when passing additional subcommand names to the `help`
-    /// subcommand. Otherwise, the more general `UnknownArgument` error is used.
+    /// subcommand. Otherwise, the more general [`UnknownArgument`] error is used.
    ///
    /// # Examples
    ///
@ -85,6 +89,9 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::UnrecognizedSubcommand);
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`InvalidSubcommand`]: ./enum.ErrorKind.html#variant.InvalidSubcommand
    /// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
    UnrecognizedSubcommand,
    /// Occurs when the user provides an empty value for an option that does not allow empty
    /// values.
@ -125,7 +132,7 @@ pub enum ErrorKind {
    /// ```
    ValueValidation,
    /// Occurs when a user provides more values for an argument than were defined by setting
-    /// `Arg::max_values`.
+    /// [`Arg::max_values`].
    ///
    /// # Examples
    ///
@ -139,9 +146,10 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::TooManyValues);
    /// ```
    /// [`Arg::max_values`]: ./struct.Arg.html#method.max_values
    TooManyValues,
    /// Occurs when the user provides fewer values for an argument than were defined by setting
-    /// `Arg::min_values`.
+    /// [`Arg::min_values`].
    ///
    /// # Examples
    ///
@ -155,10 +163,11 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::TooFewValues);
    /// ```
    /// [`Arg::min_values`]: ./struct.Arg.html#method.min_values
    TooFewValues,
    /// Occurs when the user provides a different number of values for an argument than what's
-    /// been defined by setting `Arg::number_of_values` or than was implicitly set by
+    /// been defined by setting [`Arg::number_of_values`] or than was implicitly set by
-    /// `Arg::value_names`.
+    /// [`Arg::value_names`].
    ///
    /// # Examples
    ///
@ -173,6 +182,9 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::WrongNumberOfValues);
    /// ```
    /// [`Arg::number_of_values`]
    /// [`Arg::number_of_values`]: ./struct.Arg.html#method.number_of_values
    /// [`Arg::value_names`]: ./struct.Arg.html#method.value_names
    WrongNumberOfValues,
    /// Occurs when the user provides two values which conflict with each other and can't be used
    /// together.
@ -206,8 +218,8 @@ pub enum ErrorKind {
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
    /// ```
    MissingRequiredArgument,
-    /// Occurs when a subcommand is required (as defined by `AppSettings::SubcommandRequired`), but
+    /// Occurs when a subcommand is required (as defined by [`AppSettings::SubcommandRequired`]),
-    /// the user does not provide one.
+    /// but the user does not provide one.
    ///
    /// # Examples
    ///
@ -223,9 +235,10 @@ pub enum ErrorKind {
    /// assert_eq!(err.unwrap_err().kind, ErrorKind::MissingSubcommand);
    /// # ;
    /// ```
    /// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired
    MissingSubcommand,
-    /// Occurs when either an argument or subcommand is required, as defined by
+    /// Occurs when either an argument or [`SubCommand`] is required, as defined by
-    /// `AppSettings::ArgRequiredElseHelp` but the user did not provide one.
+    /// [`AppSettings::ArgRequiredElseHelp`] but the user did not provide one.
    ///
    /// # Examples
    ///
@ -241,6 +254,8 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::MissingArgumentOrSubcommand);
    /// ```
    /// [`SubCommand`]: ./struct.SubCommand.html
    /// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp
    MissingArgumentOrSubcommand,
    /// Occurs when the user provides an argument multiple times which has not been set to allow
    /// multiple uses.
@ -259,7 +274,7 @@ pub enum ErrorKind {
    /// ```
    UnexpectedMultipleUsage,
    /// Occurs when the user provides a value containing invalid UTF-8 for an argument and
-    /// `AppSettings::StrictUtf8` is set.
+    /// [`AppSettings::StrictUtf8`] is set.
    ///
    /// # Platform Speicific
    ///
@ -282,6 +297,7 @@ pub enum ErrorKind {
    /// assert!(result.is_err());
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::InvalidUtf8);
    /// ```
    /// [`AppSettings::StrictUtf8`]: ./enum.AppSettings.html#variant.StrictUtf8
    InvalidUtf8,
    /// Not a true "error" as it means `--help` or similar was used. The help message will be sent
    /// to `stdout`.
@ -312,13 +328,19 @@ pub enum ErrorKind {
    /// assert_eq!(result.unwrap_err().kind, ErrorKind::VersionDisplayed);
    /// ```
    VersionDisplayed,
-    /// Occurs when using the `value_t!` and `values_t!` macros to convert an argument value into
+    /// Occurs when using the [`value_t!`] and [`values_t!`] macros to convert an argument value
-    /// type `T`, but the argument you requested wasn't used. I.e. you asked for an argument with
+    /// into type `T`, but the argument you requested wasn't used. I.e. you asked for an argument
-    /// name `config` to be converted, but `config` wasn't used by the user.
+    /// with name `config` to be converted, but `config` wasn't used by the user.
    /// [`value_t!`]: ./macro.value_t!.html
    /// [`values_t!`]: ./macro.values_t!.html
    ArgumentNotFound,
-    /// Represents an I/O error, typically while writing to `stderr` or `stdout`.
+    /// Represents an [I/O error], typically while writing to `stderr` or `stdout`.
    /// [I/O error]: https://doc.rust-lang.org/std/io/struct.Error.html
    Io,
-    /// Represents an Rust Display Format error, typically white writing to `stderr` or `stdout`.
+    /// Represents an Rust's [Format error] as part of [`Display`] , typically while writing to
    /// `stderr` or `stdout`.
    /// [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
    /// [Format error]: https://doc.rust-lang.org/std/fmt/struct.Error.html
    Format,
 }
--- a/src/lib.rs
+++ b/src/lib.rs
@ -1,4 +1,4 @@
-// Copyright ⓒ 2015-2016 Kevin B. Knapp and clap-rs contributors.
+// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/kbknapp/clap-rs/blob/master/CONTRIBUTORS.md).
 // Licensed under the MIT license
 // (see LICENSE or <http://opensource.org/licenses/MIT>) All files in the project carrying such
 // notice may not be copied, modified, or distributed except according to those terms.
--- a/src/macros.rs
+++ b/src/macros.rs
@ -27,11 +27,11 @@ macro_rules! load_yaml {
    );
 }
-/// Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr` from an
+/// Convenience macro getting a typed value `T` where `T` implements [`std::str::FromStr`] from an
 /// argument value. This macro returns a `Result<T,String>` which allows you as the developer to
 /// decide what you'd like to do on a failed parse. There are two types of errors, parse failures
 /// and those where the argument wasn't present (such as a non-required argument). You can use
-/// it to get a single value, or a iterator as with the `ArgMatches::values_of`
+/// it to get a single value, or a iterator as with the [`ArgMatches::values_of`]
 ///
 /// # Examples
 ///
@ -50,6 +50,9 @@ macro_rules! load_yaml {
 /// println!("{} + 2: {}", len, len + 2);
 /// # }
 /// ```
 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
 /// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of
 /// [`Result<T,String>`]: https://doc.rust-lang.org/std/result/enum.Result.html
 #[macro_export]
 macro_rules! value_t {
    ($m:ident, $v:expr, $t:ty) => {
@ -69,11 +72,11 @@ macro_rules! value_t {
    };
 }
-/// Convenience macro getting a typed value `T` where `T` implements `std::str::FromStr` or
+/// Convenience macro getting a typed value `T` where `T` implements [`std::str::FromStr`] or
-/// exiting upon error instead of returning a `Result`
+/// exiting upon error, instead of returning a [`Result`] type.
 ///
 /// **NOTE:** This macro is for backwards compatibility sake. Prefer
-/// `value_t!(/* ... */).unwrap_or_else(|e| e.exit())`
+/// [`value_t!(/* ... */).unwrap_or_else(|e| e.exit())`]
 ///
 /// # Examples
 ///
@ -92,6 +95,9 @@ macro_rules! value_t {
 /// println!("{} + 2: {}", len, len + 2);
 /// # }
 /// ```
 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
 /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
 /// [`value_t!(/* ... */).unwrap_or_else(|e| e.exit())`]: ./macro.value_t!.html
 #[macro_export]
 macro_rules! value_t_or_exit {
    ($m:ident, $v:expr, $t:ty) => {
@ -111,9 +117,9 @@ macro_rules! value_t_or_exit {
    };
 }
-/// Convenience macro getting a typed value `Vec<T>` where `T` implements `std::str::FromStr` This
+/// Convenience macro getting a typed value [`Vec<T>`] where `T` implements [`std::str::FromStr`]
-/// macro returns a `clap::Result<Vec<T>>` (`Result<Vec<T>, clap::Error>`) which allows you as the
+/// This macro returns a [`clap::Result<Vec<T>>`] which allows you as the developer to decide
-/// developer to decide what you'd like to do on a failed parse.
+/// what you'd like to do on a failed parse.
 ///
 /// # Examples
 ///
@ -137,6 +143,9 @@ macro_rules! value_t_or_exit {
 /// }
 /// # }
 /// ```
 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
 /// [`Vec<T>`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
 /// [`clap::Result<Vec<T>>`]: ./type.Result.html
 #[macro_export]
 macro_rules! values_t {
    ($m:ident, $v:expr, $t:ty) => {
@ -166,11 +175,11 @@ macro_rules! values_t {
    };
 }
-/// Convenience macro getting a typed value `Vec<T>` where `T` implements `std::str::FromStr` or
+/// Convenience macro getting a typed value [`Vec<T>`] where `T` implements [`std::str::FromStr`]
-/// exiting upon error.
+/// or exiting upon error.
 ///
 /// **NOTE:** This macro is for backwards compatibility sake. Prefer
-/// `values_t!(/* ... */).unwrap_or_else(|e| e.exit())`
+/// [`values_t!(/* ... */).unwrap_or_else(|e| e.exit())`]
 ///
 /// # Examples
 ///
@ -195,6 +204,9 @@ macro_rules! values_t {
 /// }
 /// # }
 /// ```
 /// [`values_t!(/* ... */).unwrap_or_else(|e| e.exit())`]: ./macro.values_t!.html
 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
 /// [`Vec<T>`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
 #[macro_export]
 macro_rules! values_t_or_exit {
    ($m:ident, $v:expr, $t:ty) => {
@ -243,12 +255,12 @@ macro_rules! _clap_count_exprs {
 /// Convenience macro to generate more complete enums with variants to be used as a type when
 /// parsing arguments. This enum also provides a `variants()` function which can be used to
-/// retrieve a `Vec<&'static str>` of the variant names, as well as implementing `FromStr` and
+/// retrieve a `Vec<&'static str>` of the variant names, as well as implementing [`FromStr`] and
-/// `Display` automatically.
+/// [`Display`] automatically.
 ///
 /// **NOTE:** Case insensitivity is supported for ASCII characters only
 ///
-/// **NOTE:** This macro automatically implements std::str::FromStr and std::fmt::Display
+/// **NOTE:** This macro automatically implements [`std::str::FromStr`] and [`std::fmt::Display`]
 ///
 /// **NOTE:** These enums support pub (or not) and uses of the #[derive()] traits
 ///
@ -277,6 +289,10 @@ macro_rules! _clap_count_exprs {
 ///     // Use f like any other Foo variant...
 /// }
 /// ```
 /// [`FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
 /// [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
 /// [`std::fmt::Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
 #[macro_export]
 macro_rules! arg_enum {
    (@as_item $($i:item)*) => ($($i)*);