Merge pull request #3475 from epage/fixes

docs: Polish in prep for 3.1.0

CHANGELOG.md

@@ -24,6 +24,7 @@ Changes in behavior of note that are not guaranteed to be compatible across rele
 - *(error)* Deprecate `clap::AppSettings::WaitOnError`, leaving it to the user to implement
 - *(validation)* `clap::Command::subcommand_required(true).arg_required_else_help(true)` is now preferred over `clap::AppSettings::SubcommandRequiredElseHelp` (#3280)
 - *(builder)* `clap::AppSettings` are nearly all deprecated and replaced with builder methods and getters (#2717)
+- *(builder)* `clap::ArgSettings` is deprecated and replaced with builder methods and getters (#2717)
 - *(builder)* `clap::Arg::id` and `clap::ArgGroup::id` are now preferred over `clap::Arg::name` and `clap::ArgGroup::name` (#3335)
 - *(help)* `clap::Command::next_help_heading` is now preferred over `clap::Command::help_heading` (#1807, #1553)
 - *(error)* `clap::error::ErrorKind` is now preferred over `clap::ErrorKind` (#3395)

CONTRIBUTING.md

@@ -35,11 +35,11 @@ There are a few goals of `clap` that I'd like to maintain throughout contributio
 
 Our releases fall into one of:
 - Major releases which are reserved for breaking changes
-  - Released approximately every 6 months
+  - Aspire to at least 6-9 months between releases
   - Remove all deprecated functionality
   - Try to minimize new breaking changes to ease user transition and reduce time "we go dark" (unreleased feature-branch)
 - Minor releases which are for minor compatibility changes
-  - Released approximately every 2 months
+  - Aspire to at least 2 months between releases
   - Changes to MSRV
   - Deprecating existing functionality
   - `#[doc(hidden)]` all deprecated items in the prior minor release

src/build/arg.rs

@@ -35,6 +35,12 @@ use crate::build::RegexRef;
 /// 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.
 ///
+/// - [Basic API][crate::Arg#basic-api]
+/// - [Value Handling][crate::Arg#value-handling]
+/// - [Help][crate::Arg#help-1]
+/// - [Advanced Argument Relations][crate::Arg#advanced-argument-relations]
+/// - [Reflection][crate::Arg#reflection]
+///
 /// # Examples
 ///
 /// ```rust
@@ -91,6 +97,7 @@ pub struct Arg<'help> {
     pub(crate) value_hint: ValueHint,
 }
 
+/// # Basic API
 impl<'help> Arg<'help> {
     /// Create a new [`Arg`] with a unique name.
     ///
@@ -946,7 +953,7 @@ impl<'help> Arg<'help> {
     }
 }
 
-/// Value handling
+/// # Value Handling
 impl<'help> Arg<'help> {
     /// Specifies that the argument takes a value at run time.
     ///
@@ -2727,7 +2734,7 @@ impl<'help> Arg<'help> {
     }
 }
 
-/// Help
+/// # Help
 impl<'help> Arg<'help> {
     /// Sets the description of the argument for short help (`-h`).
     ///
@@ -3284,7 +3291,7 @@ impl<'help> Arg<'help> {
     }
 }
 
-/// Advanced argument relations
+/// # Advanced Argument Relations
 impl<'help> Arg<'help> {
     /// The name of the [`ArgGroup`] the argument belongs to.
     ///
@@ -4489,7 +4496,7 @@ impl<'help> Arg<'help> {
     }
 }
 
-/// Reflection
+/// # Reflection
 impl<'help> Arg<'help> {
     /// Get the name of the argument
     #[inline]
@@ -4800,7 +4807,7 @@ impl<'help> Arg<'help> {
     }
 }
 
-/// Deprecated
+/// # Deprecated
 impl<'help> Arg<'help> {
     /// Deprecated, replaced with [`Arg::new`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::new`")]
@@ -5017,7 +5024,7 @@ impl<'help> Arg<'help> {
     }
 }
 
-// Internally used only
+/// # Internally used only
 impl<'help> Arg<'help> {
     pub(crate) fn _build(&mut self) {
         if self.is_positional() {

src/build/command.rs

@@ -43,6 +43,12 @@ use crate::build::debug_asserts::assert_app;
 /// [`CommandFactory::into_app`][crate::CommandFactory::into_app] to access the
 /// `Command`.
 ///
+/// - [Basic API][crate::App#basic-api]
+/// - [Application-wide Settings][crate::App#application-wide-settings]
+/// - [Command-specific Settings][crate::App#command-specific-settings]
+/// - [Subcommand-specific Settings][crate::App#subcommand-specific-settings]
+/// - [Reflection][crate::App#reflection]
+///
 /// # Examples
 ///
 /// ```no_run
@@ -103,7 +109,7 @@ pub struct App<'help> {
     subcommand_heading: Option<&'help str>,
 }
 
-/// Basic API
+/// # Basic API
 impl<'help> App<'help> {
     /// Creates a new instance of an `Command`.
     ///
@@ -837,7 +843,7 @@ impl<'help> App<'help> {
     }
 }
 
-/// Command-wide Settings
+/// # Application-wide Settings
 ///
 /// These settings will apply to the top-level command and all subcommands, by default.  Some
 /// settings can be overridden in subcommands.
@@ -1323,7 +1329,7 @@ impl<'help> App<'help> {
     }
 }
 
-/// Command-specific Settings
+/// # Command-specific Settings
 ///
 /// These apply only to the current command and are not inherited by subcommands.
 impl<'help> App<'help> {
@@ -2173,7 +2179,7 @@ impl<'help> App<'help> {
     }
 }
 
-/// Subcommand-specific Settings
+/// # Subcommand-specific Settings
 impl<'help> App<'help> {
     /// Sets the short version of the subcommand flag without the preceding `-`.
     ///
@@ -3154,7 +3160,7 @@ impl<'help> App<'help> {
     }
 }
 
-/// Reflection
+/// # Reflection
 impl<'help> App<'help> {
     #[inline]
     pub(crate) fn get_usage_name(&self) -> Option<&str> {

src/lib.rs

@@ -57,7 +57,6 @@ pub use clap_derive::{self, *};
 
 /// Deprecated, replaced with [`CommandFactory`]
 #[deprecated(since = "3.0.0", note = "Replaced with `CommandFactory`")]
-#[doc(hidden)]
 pub use CommandFactory as IntoApp;
 /// Deprecated, replaced with [`Parser`]
 #[deprecated(since = "3.0.0", note = "Replaced with `Parser`")]

src/parse/matches/arg_matches.rs

@@ -626,10 +626,7 @@ impl ArgMatches {
         self.args.contains_key(&id)
     }
 
-    /// Check if an argument was present at runtime.
-    ///
-    /// *NOTE:* This will always return `true` if [`default_value`] has been set.
-    /// [`occurrences_of`] can be used to check if a value is present at runtime.
+    /// Report where argument value came from
     ///
     /// # Panics
     ///
@@ -638,7 +635,7 @@ impl ArgMatches {
     /// # Examples
     ///
     /// ```rust
-    /// # use clap::{Command, Arg};
+    /// # use clap::{Command, Arg, ValueSource};
     /// let m = Command::new("myprog")
     ///     .arg(Arg::new("debug")
     ///         .short('d'))
@@ -646,7 +643,7 @@ impl ArgMatches {
     ///         "myprog", "-d"
     ///     ]);
     ///
-    /// assert!(m.is_present("debug"));
+    /// assert_eq!(m.value_source("debug"), Some(ValueSource::CommandLine));
     /// ```
     ///
     /// [`default_value`]: crate::Arg::default_value()