Merge pull request #6125 from epage/docs

docs: Try to clarify several points

Author: epage

clap_builder/src/builder/command.rs

@@ -624,6 +624,13 @@ impl Command {
 
     /// Custom error message for post-parsing validation
     ///
+    /// **Note:** this will ensure the `Command` has been sufficiently [built][Command::build] for any
+    /// relevant context, including usage.
+    ///
+    /// # Panics
+    ///
+    /// If contradictory arguments or settings exist (debug builds).
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -906,6 +913,12 @@ impl Command {
     ///
     /// See also [`Command::print_long_help`].
     ///
+    /// **Note:** this will ensure the `Command` has been sufficiently [built][Command::build].
+    ///
+    /// # Panics
+    ///
+    /// If contradictory arguments or settings exist (debug builds).
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -931,6 +944,12 @@ impl Command {
     ///
     /// See also [`Command::print_help`].
     ///
+    /// **Note:** this will ensure the `Command` has been sufficiently [built][Command::build].
+    ///
+    /// # Panics
+    ///
+    /// If contradictory arguments or settings exist (debug builds).
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -959,6 +978,12 @@ impl Command {
     ///
     /// See also [`Command::render_long_help`].
     ///
+    /// **Note:** this will ensure the `Command` has been sufficiently [built][Command::build].
+    ///
+    /// # Panics
+    ///
+    /// If contradictory arguments or settings exist (debug builds).
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -986,6 +1011,12 @@ impl Command {
     ///
     /// See also [`Command::render_help`].
     ///
+    /// **Note:** this will ensure the `Command` has been sufficiently [built][Command::build].
+    ///
+    /// # Panics
+    ///
+    /// If contradictory arguments or settings exist (debug builds).
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1091,6 +1122,12 @@ impl Command {
 
     /// Usage statement
     ///
+    /// **Note:** this will ensure the `Command` has been sufficiently [built][Command::build].
+    ///
+    /// # Panics
+    ///
+    /// If contradictory arguments or settings exist (debug builds).
+    ///
     /// ### Examples
     ///
     /// ```rust

src/_derive/mod.rs

@@ -320,7 +320,7 @@
 //! | `Option<Vec<Vec<T>>>` | `0..` occurrences of argument, grouped by occurrence | `.action(ArgAction::Append).required(false)`  | requires `unstable-v5` |
 //!
 //! In addition, [`.value_parser(value_parser!(T))`][crate::value_parser!] is called for each
-//! field.
+//! field in the absence of a [`#[arg(value_parser)]` attribute](#arg-attributes).
 //!
 //! Notes:
 //! - For custom type behavior, you can override the implied attributes/settings and/or set additional ones