Merge pull request #4348 from mattmadeofpasta/clarify_no_long_help_text_for_possiblevalue

Clarify that the "body" part of the doc comment on a `ValueEnum` is ignored

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

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"),
         })
     }
 }

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

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,
 }
 

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]