Repository: clap-rs/clap
Pull request #4348 (2022-10-04 18:09:08)

Clarify that the "body" part of the doc comment on a `ValueEnum` is ignored
`PossibleValue` does not have a long help text and the "body" part of the doc comment on a `ValueEnum` is ignored.

Improve a test case and the example to clarify this behavior.


Patch:
diff --git a/examples/tutorial_builder/04_01_enum.md b/examples/tutorial_builder/04_01_enum.md
index ef67bc80..858f2f38 100644
--- a/examples/tutorial_builder/04_01_enum.md
+++ b/examples/tutorial_builder/04_01_enum.md
@@ -4,11 +4,31 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage: 04_01_enum[EXE] <MODE>
 
+Arguments:
+  <MODE>
+          What mode to run the program in
+
+          Possible values:
+          - fast: Run swiftly
+          - slow: Crawl slowly but steadily
+
+Options:
+  -h, --help
+          Print help information (use `-h` for a summary)
+
+  -V, --version
+          Print version information
+
+$ 04_01_enum -h
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_01_enum[EXE] <MODE>
+
 Arguments:
   <MODE>  What mode to run the program in [possible values: fast, slow]
 
 Options:
-  -h, --help     Print help information
+  -h, --help     Print help information (use `--help` for more detail)
   -V, --version  Print version information
 
 $ 04_01_enum fast
diff --git a/examples/tutorial_builder/04_01_enum.rs b/examples/tutorial_builder/04_01_enum.rs
index 3f8ddd3a..a8b0e685 100644
--- a/examples/tutorial_builder/04_01_enum.rs
+++ b/examples/tutorial_builder/04_01_enum.rs
@@ -14,8 +14,8 @@ impl ValueEnum for Mode {
 
     fn to_possible_value<'a>(&self) -> Option<PossibleValue> {
         Some(match self {
-            Mode::Fast => PossibleValue::new("fast"),
-            Mode::Slow => PossibleValue::new("slow"),
+            Mode::Fast => PossibleValue::new("fast").help("Run swiftly"),
+            Mode::Slow => PossibleValue::new("slow").help("Crawl slowly but steadily"),
         })
     }
 }
diff --git a/examples/tutorial_derive/04_01_enum.md b/examples/tutorial_derive/04_01_enum.md
index f6f39779..18db5e0d 100644
--- a/examples/tutorial_derive/04_01_enum.md
+++ b/examples/tutorial_derive/04_01_enum.md
@@ -4,11 +4,31 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage: 04_01_enum_derive[EXE] <MODE>
 
+Arguments:
+  <MODE>
+          What mode to run the program in
+
+          Possible values:
+          - fast: Run swiftly
+          - slow: Crawl slowly but steadily
+
+Options:
+  -h, --help
+          Print help information (use `-h` for a summary)
+
+  -V, --version
+          Print version information
+
+$ 04_01_enum_derive -h
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_01_enum_derive[EXE] <MODE>
+
 Arguments:
   <MODE>  What mode to run the program in [possible values: fast, slow]
 
 Options:
-  -h, --help     Print help information
+  -h, --help     Print help information (use `--help` for more detail)
   -V, --version  Print version information
 
 $ 04_01_enum_derive fast
diff --git a/examples/tutorial_derive/04_01_enum.rs b/examples/tutorial_derive/04_01_enum.rs
index 078fc5d1..41410a3b 100644
--- a/examples/tutorial_derive/04_01_enum.rs
+++ b/examples/tutorial_derive/04_01_enum.rs
@@ -10,7 +10,11 @@ struct Cli {
 
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)]
 enum Mode {
+    /// Run swiftly
     Fast,
+    /// Crawl slowly but steadily
+    ///
+    /// This paragraph is ignored because there is no long help text for possible values.
     Slow,
 }
 


Test patch:
diff --git a/tests/derive/doc_comments_help.rs b/tests/derive/doc_comments_help.rs
index d6d3db3d..8aa4fa1e 100644
--- a/tests/derive/doc_comments_help.rs
+++ b/tests/derive/doc_comments_help.rs
@@ -212,14 +212,26 @@ fn multiline_separates_default() {
 }
 
 #[test]
-fn argenum_multiline_doc_comment() {
-    #[derive(ValueEnum, Clone)]
+fn value_enum_multiline_doc_comment() {
+    #[derive(Parser, Debug)]
+    struct Command {
+        x: LoremIpsum,
+    }
+
+    #[derive(ValueEnum, Clone, PartialEq, Debug)]
     enum LoremIpsum {
-        /// Multiline
+        /// Doc comment summary
         ///
-        /// Doc comment
+        /// The doc comment body is ignored
         Bar,
     }
+
+    let help = utils::get_long_help::<Command>();
+
+    assert!(help.contains("Doc comment summary"));
+
+    // There is no long help text for possible values. The long help only contains the summary.
+    assert!(!help.contains("The doc comment body is ignored"));
 }
 
 #[test]