From 3ffcffb21f46bc43b18f300a37b36747a162af75 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Sat, 16 Oct 2021 13:42:33 -0500
Subject: [PATCH] docs: Clarify corner caseses with default values

This is meant to lower the chance of confusion with cases like #2714 and #1586.

This is not meant to be exhaustive, looked at the mentioned cases in
that issue and pattern matched on other ones mentioning "is present".
---
 src/build/arg/mod.rs   | 12 ++++++++++++
 src/build/arg_group.rs | 10 ++++++++++
 2 files changed, 22 insertions(+)

diff --git a/src/build/arg/mod.rs b/src/build/arg/mod.rs
index 4a1bdb9290fe..20e6d3770019 100644
--- a/src/build/arg/mod.rs
+++ b/src/build/arg/mod.rs
@@ -1045,6 +1045,8 @@ impl<'help> Arg<'help> {
     ///
     /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
     ///
+    /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1095,6 +1097,8 @@ impl<'help> Arg<'help> {
     ///
     /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
     ///
+    /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1328,6 +1332,8 @@ impl<'help> Arg<'help> {
     ///
     /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
     ///
+    /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1389,6 +1395,8 @@ impl<'help> Arg<'help> {
     /// if this arg (`self`) is present and its value equals to `val`.
     /// If it does, `another_arg` will be marked as required.
     ///
+    /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1510,6 +1518,8 @@ impl<'help> Arg<'help> {
     /// Allows specifying that this argument is [required] only if the specified
     /// `arg` is present at runtime and its value equals `val`.
     ///
+    /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1786,6 +1796,8 @@ impl<'help> Arg<'help> {
     /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
     /// by default.
     ///
+    /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
diff --git a/src/build/arg_group.rs b/src/build/arg_group.rs
index 809441c573c5..83d4ad1187d8 100644
--- a/src/build/arg_group.rs
+++ b/src/build/arg_group.rs
@@ -249,6 +249,8 @@ impl<'help> ArgGroup<'help> {
     /// Use of more than one arg is an error." Vice setting `ArgGroup::multiple(true)` which
     /// states, '*At least* one arg from this group must be used. Using multiple is OK."
     ///
+    /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -284,6 +286,8 @@ impl<'help> ArgGroup<'help> {
     ///
     /// **NOTE:** The name provided may be an argument, or group name
     ///
+    /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -319,6 +323,8 @@ impl<'help> ArgGroup<'help> {
     ///
     /// **NOTE:** The names provided may be an argument, or group name
     ///
+    /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -357,6 +363,8 @@ impl<'help> ArgGroup<'help> {
     ///
     /// **NOTE:** The name provided may be an argument, or group name
     ///
+    /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -389,6 +397,8 @@ impl<'help> ArgGroup<'help> {
     ///
     /// **NOTE:** The names provided may be an argument, or group name
     ///
+    /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
+    ///
     /// # Examples
     ///
     /// ```rust