wip

clap_derive/Cargo.toml

@@ -33,6 +33,8 @@ syn = { version = "2.0.8", features = ["full"] }
 quote = "1.0.9"
 proc-macro2 = "1.0.69"
 heck = "0.5.0"
+pulldown-cmark = { version = "0.12.2", default-features = false }
+anstyle = "1.0.10"
 
 [features]
 default = []

clap_derive/src/utils/doc_comments.rs

@@ -3,7 +3,9 @@
 //! #[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 std::fmt::Write;
 use std::iter;
+use std::ops::AddAssign;
 
 pub(crate) fn extract_doc_comment(attrs: &[syn::Attribute]) -> Vec<String> {
     // multiline comments (`/** ... */`) may have LFs (`\n`) in them,
@@ -54,35 +56,137 @@ pub(crate) fn format_doc_comment(
     preprocess: bool,
     force_long: bool,
 ) -> (Option<String>, Option<String>) {
-    if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) {
-        let (short, long) = if preprocess {
-            let paragraphs = split_paragraphs(lines);
-            let short = paragraphs[0].clone();
-            let long = paragraphs.join("\n\n");
-            (remove_period(short), long)
-        } else {
-            let short = lines[..first_blank].join("\n");
-            let long = lines.join("\n");
-            (short, long)
-        };
+    if preprocess {
+        let (short, long) = parse_markdown(lines);
+        let long = long.or_else(|| force_long.then(|| short.clone()));
+
+        (Some(short), long)
+    } else if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) {
+        let short = lines[..first_blank].join("\n");
+        let long = lines.join("\n");
 
         (Some(short), Some(long))
     } else {
-        let (short, long) = if preprocess {
-            let short = merge_lines(lines);
-            let long = force_long.then(|| short.clone());
-            let short = remove_period(short);
-            (short, long)
-        } else {
-            let short = lines.join("\n");
-            let long = force_long.then(|| short.clone());
-            (short, long)
-        };
+        let short = lines.join("\n");
+        let long = force_long.then(|| short.clone());
 
         (Some(short), long)
     }
 }
 
+fn parse_markdown(input: &[String]) -> (String, Option<String>) {
+    use anstyle::Style;
+    use pulldown_cmark::*;
+    let input = input.join("\n");
+    let input = Parser::new_ext(
+        &input,
+        Options::ENABLE_STRIKETHROUGH | Options::ENABLE_SMART_PUNCTUATION,
+    );
+    let mut text = String::new();
+    let heading = Style::new().bold();
+    let emphasis = Style::new().italic();
+    let strong = Style::new().bold();
+    let strike_through = Style::new().strikethrough();
+    let link = Style::new().underline();
+    let mut list_indices = Vec::new();
+    // let list_symbol = '●';
+    let list_symbol = '•';
+    let tab_width = 2;
+    for event in input {
+        match event {
+            Event::Start(Tag::Paragraph) => { /* nothing to do */ }
+            Event::Start(Tag::Heading { .. }) => write!(text, "{heading}").unwrap(),
+            Event::Start(
+                Tag::Image { .. } | Tag::BlockQuote(_) | Tag::CodeBlock(_) | Tag::HtmlBlock,
+            ) => { /* IGNORED */ }
+            Event::Start(Tag::List(list_start)) => {
+                list_indices.push(list_start);
+                if !text.is_empty() && !text.ends_with('\n') {
+                    text.push('\n');
+                }
+            }
+            Event::Start(Tag::Item) => {
+                // TODO consider styling list
+                write!(text, "{:1$}", "", tab_width * list_indices.len()).unwrap();
+                if let Some(Some(index)) = list_indices.last_mut() {
+                    write!(text, "{index}. ").unwrap();
+                    index.add_assign(1);
+                } else {
+                    write!(text, "{list_symbol} ").unwrap();
+                }
+            }
+            Event::Start(Tag::Emphasis) => write!(text, "{emphasis}").unwrap(),
+            Event::Start(Tag::Strong) => write!(text, "{strong}").unwrap(),
+            Event::Start(Tag::Strikethrough) => write!(text, "{strike_through}").unwrap(),
+            Event::Start(Tag::Link { dest_url, .. }) => {
+                write!(text, "\x1B]8;;{dest_url}\x1B\\{link}").unwrap();
+            }
+
+            Event::End(TagEnd::Paragraph) => text.push_str("\n\n"),
+            Event::End(TagEnd::Heading(..)) => write!(text, "{heading:#}\n\n").unwrap(),
+            Event::End(TagEnd::List(_)) => {
+                list_indices.pop().unwrap();
+            }
+            Event::End(TagEnd::Item) => {
+                if !text.ends_with('\n') {
+                    text.push('\n');
+                }
+            }
+            Event::End(TagEnd::Emphasis) => write!(text, "{emphasis:#}").unwrap(),
+            Event::End(TagEnd::Strong) => write!(text, "{strong:#}").unwrap(),
+            Event::End(TagEnd::Strikethrough) => write!(text, "{strike_through:#}").unwrap(),
+            Event::End(TagEnd::Link) => write!(text, "\x1B]8;;\x1B\\{link:#}").unwrap(),
+            Event::End(
+                TagEnd::Image | TagEnd::BlockQuote(_) | TagEnd::HtmlBlock | TagEnd::CodeBlock,
+            ) => { /* IGNORED */ }
+
+            Event::Text(segment) => text.push_str(&segment),
+            Event::Code(code) => {
+                // TODO questionable
+                write!(text, "{0}{code}{0:#}", Style::new().dimmed()).unwrap();
+            }
+            // There is not really anything useful to do with block level html.
+            Event::Html(html) => text.push_str(&html),
+            // At some point we could support custom tags like `<red>`
+            Event::InlineHtml(html) => text.push_str(&html),
+            Event::SoftBreak => text.push(' '),
+            Event::HardBreak => text.push('\n'),
+            Event::Rule => { /* ignored */ }
+
+            Event::Start(
+                Tag::FootnoteDefinition(_)
+                | Tag::DefinitionList
+                | Tag::DefinitionListTitle
+                | Tag::DefinitionListDefinition
+                | Tag::Table(_)
+                | Tag::TableHead
+                | Tag::TableRow
+                | Tag::TableCell
+                | Tag::MetadataBlock(_),
+            )
+            | Event::End(
+                TagEnd::FootnoteDefinition
+                | TagEnd::DefinitionList
+                | TagEnd::DefinitionListTitle
+                | TagEnd::DefinitionListDefinition
+                | TagEnd::Table
+                | TagEnd::TableHead
+                | TagEnd::TableRow
+                | TagEnd::TableCell
+                | TagEnd::MetadataBlock(_),
+            )
+            | Event::InlineMath(_)
+            | Event::DisplayMath(_)
+            | Event::FootnoteReference(_)
+            | Event::TaskListMarker(_) => {
+                unimplemented!("feature not enabled {event:?}")
+            }
+        }
+    }
+    let text = text.trim();
+    (text.to_owned(), Some(text.to_owned()))
+}
+
 fn split_paragraphs(lines: &[String]) -> Vec<String> {
     let mut last_line = 0;
     iter::from_fn(|| {

examples/markdown-derive.rs

@@ -0,0 +1,37 @@
+use clap::Parser;
+
+/// # Long help
+/// 
+/// This should only be printed for long help.
+/// # Help
+/// 
+/// This should be printed for both short and long help.
+#[derive(Parser, Debug)]
+struct Args {
+    /// This is _italic and **bold** just italic_ ~struck through~.
+    #[arg(short, long)]
+    name: String,
+
+    /// Short help
+    ///
+    /// Only in long help:
+    ///
+    /// 3. This
+    /// 5. is
+    ///    1. a
+    ///    2. multi level
+    /// 5. list
+    ///
+    /// - so
+    ///   - is
+    ///     - this
+    ///       - even
+    ///   - though
+    /// - unordered
+    #[arg(short, long, default_value_t = 1)]
+    count: u8,
+}
+
+fn main() {
+    Args::parse();
+}