Merge pull request #4460 from epage/help

refactor(derive): Clean up doc comment handling

clap_derive/src/item.rs

@@ -17,7 +17,7 @@ use std::env;
 use heck::{ToKebabCase, ToLowerCamelCase, ToShoutySnakeCase, ToSnakeCase, ToUpperCamelCase};
 use proc_macro2::{self, Span, TokenStream};
 use proc_macro_error::abort;
-use quote::{quote, quote_spanned, ToTokens};
+use quote::{format_ident, quote, quote_spanned, ToTokens};
 use syn::DeriveInput;
 use syn::{
     self, ext::IdentExt, spanned::Spanned, Attribute, Field, Ident, LitStr, MetaNameValue, Type,
@@ -155,9 +155,6 @@ impl Item {
                         "methods are not allowed for flattened entry"
                     );
                 }
-
-                // ignore doc comments
-                res.doc_comment = vec![];
             }
 
             Kind::Subcommand(_)
@@ -231,9 +228,6 @@ impl Item {
                         "methods are not allowed for flattened entry"
                     );
                 }
-
-                // ignore doc comments
-                res.doc_comment = vec![];
             }
 
             Kind::Subcommand(_) => {
@@ -896,10 +890,27 @@ impl Item {
             })
             .collect();
 
-        let (short, long) = process_doc_comment(comment_parts, name, !self.verbatim_doc_comment);
-        self.doc_comment.extend(short);
-        if supports_long_help {
-            self.doc_comment.extend(long);
+        if let Some((short_help, long_help)) =
+            process_doc_comment(&comment_parts, !self.verbatim_doc_comment)
+        {
+            let short_name = format_ident!("{}", name);
+            let short = Method::new(
+                short_name,
+                short_help
+                    .map(|h| quote!(#h))
+                    .unwrap_or_else(|| quote!(None)),
+            );
+            self.doc_comment.push(short);
+            if supports_long_help {
+                let long_name = format_ident!("long_{}", name);
+                let long = Method::new(
+                    long_name,
+                    long_help
+                        .map(|h| quote!(#h))
+                        .unwrap_or_else(|| quote!(None)),
+                );
+                self.doc_comment.push(long);
+            }
         }
     }
 

clap_derive/src/utils/doc_comments.rs

@@ -3,16 +3,12 @@
 //! #[derive(Parser)] works in terms of "paragraphs". Paragraph is a sequence of
 //! non-empty adjacent lines, delimited by sequences of blank (whitespace only) lines.
 
-use crate::item::Method;
-
-use quote::{format_ident, quote};
 use std::iter;
 
 pub fn process_doc_comment(
-    lines: Vec<String>,
-    name: &str,
+    lines: &[String],
     preprocess: bool,
-) -> (Option<Method>, Option<Method>) {
+) -> Option<(Option<String>, Option<String>)> {
     // multiline comments (`/** ... */`) may have LFs (`\n`) in them,
     // we need to split so we could handle the lines correctly
     //
@@ -27,19 +23,14 @@ pub fn process_doc_comment(
         lines.pop();
     }
 
-    // remove one leading space no matter what
-    for line in lines.iter_mut() {
-        if line.starts_with(' ') {
-            *line = &line[1..];
-        }
-    }
-
     if lines.is_empty() {
-        return (None, None);
+        return None;
     }
 
-    let short_name = format_ident!("{}", name);
-    let long_name = format_ident!("long_{}", name);
+    // remove one leading space no matter what
+    for line in lines.iter_mut() {
+        *line = line.strip_prefix(' ').unwrap_or(line);
+    }
 
     if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) {
         let (short, long) = if preprocess {
@@ -53,10 +44,7 @@ pub fn process_doc_comment(
             (short, long)
         };
 
-        (
-            Some(Method::new(short_name, quote!(#short))),
-            Some(Method::new(long_name, quote!(#long))),
-        )
+        Some((Some(short), Some(long)))
     } else {
         let short = if preprocess {
             let s = merge_lines(&lines);
@@ -65,10 +53,7 @@ pub fn process_doc_comment(
             lines.join("\n")
         };
 
-        (
-            Some(Method::new(short_name, quote!(#short))),
-            Some(Method::new(long_name, quote!(None))),
-        )
+        Some((Some(short), None))
     }
 }