Merge pull request #5887 from epage/positional

docs: Clarify the default state of an Arg/field

clap_builder/src/builder/arg.rs

@@ -98,6 +98,10 @@ impl Arg {
     /// The name is used to check whether or not the argument was used at
     /// runtime, get values, set relationships with other args, etc..
     ///
+    /// By default, an `Arg` is
+    /// - Positional, see [`Arg::short`] or [`Arg::long`] turn it into an option
+    /// - Accept a single value, see [`Arg::action`] to override this
+    ///
     /// <div class="warning">
     ///
     /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::action(ArgAction::Set)`])

src/_derive/_tutorial/chapter_2.rs

@@ -10,7 +10,7 @@
 //!
 //! ### Positionals
 //!
-//! You can have users specify values by their position on the command-line:
+//! By default, struct fields define positional arguments:
 //!
 //! ```rust
 #![doc = include_str!("../../../examples/tutorial_derive/03_03_positional.rs")]

src/_derive/mod.rs

@@ -220,6 +220,9 @@
 //! ### Arg Attributes
 //!
 //! These correspond to a [`Arg`][crate::Arg].
+//! The default state for a field without attributes is to be a positional argument with [behavior
+//! inferred from the field type](#arg-types).
+//! `#[arg(...)]` attributes allow overriding or extending those defaults.
 //!
 //! **Raw attributes:**  Any [`Arg` method][crate::Arg] can also be used as an attribute, see [Terminology](#terminology) for syntax.
 //! - e.g. `#[arg(num_args(..=3))]` would translate to `arg.num_args(..=3)`

src/_tutorial/chapter_2.rs

@@ -9,7 +9,7 @@
 //!
 //! ### Positionals
 //!
-//! You can have users specify values by their position on the command-line:
+//! By default, an [`Arg`] defines a positional argument:
 //!
 //! ```rust
 #![doc = include_str!("../../examples/tutorial_builder/03_03_positional.rs")]