From d1db3d2f0e8a71fb82c7d257ed30d9f7d52f5563 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 7 Nov 2022 07:48:16 -0600 Subject: [PATCH 1/4] refactor(derive): Clarify empty doc needs --- clap_derive/src/utils/doc_comments.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/clap_derive/src/utils/doc_comments.rs b/clap_derive/src/utils/doc_comments.rs index 0da1f3b0267..7327de8ac4b 100644 --- a/clap_derive/src/utils/doc_comments.rs +++ b/clap_derive/src/utils/doc_comments.rs @@ -27,6 +27,10 @@ pub fn process_doc_comment( lines.pop(); } + if lines.is_empty() { + return (None, None); + } + // remove one leading space no matter what for line in lines.iter_mut() { if line.starts_with(' ') { @@ -34,10 +38,6 @@ pub fn process_doc_comment( } } - if lines.is_empty() { - return (None, None); - } - let short_name = format_ident!("{}", name); let long_name = format_ident!("long_{}", name); From 6ace0410c182a1c17930b218fee9dfeb87db454f Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 7 Nov 2022 07:49:44 -0600 Subject: [PATCH 2/4] refactor(derive): Clarify leading-space removal --- clap_derive/src/utils/doc_comments.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/clap_derive/src/utils/doc_comments.rs b/clap_derive/src/utils/doc_comments.rs index 7327de8ac4b..fa728aa982a 100644 --- a/clap_derive/src/utils/doc_comments.rs +++ b/clap_derive/src/utils/doc_comments.rs @@ -33,9 +33,7 @@ pub fn process_doc_comment( // remove one leading space no matter what for line in lines.iter_mut() { - if line.starts_with(' ') { - *line = &line[1..]; - } + *line = line.strip_prefix(' ').unwrap_or(line); } let short_name = format_ident!("{}", name); From 5ee9e0fe76845f0edc40c1167292b0636ec05a21 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 7 Nov 2022 08:06:10 -0600 Subject: [PATCH 3/4] refactor(derive): Decouple doc comment parsing from methods --- clap_derive/src/item.rs | 27 ++++++++++++++++++++++----- clap_derive/src/utils/doc_comments.rs | 23 +++++------------------ 2 files changed, 27 insertions(+), 23 deletions(-) diff --git a/clap_derive/src/item.rs b/clap_derive/src/item.rs index b9f64da6499..933c95d4ad7 100644 --- a/clap_derive/src/item.rs +++ b/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, @@ -896,10 +896,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); + } } } diff --git a/clap_derive/src/utils/doc_comments.rs b/clap_derive/src/utils/doc_comments.rs index fa728aa982a..591246ff2ef 100644 --- a/clap_derive/src/utils/doc_comments.rs +++ b/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, - name: &str, + lines: &[String], preprocess: bool, -) -> (Option, Option) { +) -> Option<(Option, Option)> { // multiline comments (`/** ... */`) may have LFs (`\n`) in them, // we need to split so we could handle the lines correctly // @@ -28,7 +24,7 @@ pub fn process_doc_comment( } if lines.is_empty() { - return (None, None); + return None; } // remove one leading space no matter what @@ -36,9 +32,6 @@ pub fn process_doc_comment( *line = line.strip_prefix(' ').unwrap_or(line); } - let short_name = format_ident!("{}", name); - let long_name = format_ident!("long_{}", name); - if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) { let (short, long) = if preprocess { let paragraphs = split_paragraphs(&lines); @@ -51,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); @@ -63,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)) } } From 73be1fef9941b1473f8a91b239c3e11dd34bf8a0 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 7 Nov 2022 08:08:06 -0600 Subject: [PATCH 4/4] refactor(derive): Remove dead code --- clap_derive/src/item.rs | 6 ------ 1 file changed, 6 deletions(-) diff --git a/clap_derive/src/item.rs b/clap_derive/src/item.rs index 933c95d4ad7..94f1226787c 100644 --- a/clap_derive/src/item.rs +++ b/clap_derive/src/item.rs @@ -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(_) => {