mithril_doc_derive/
doc.rs

1//! The preprocessing we apply to doc comments.
2//!
3//! #[derive(Parser)] works in terms of "paragraphs". Paragraph is a sequence of
4//! non-empty adjacent lines, delimited by sequences of blank (whitespace only) lines.
5
6// From https://github1s.com/clap-rs/clap/tree/master clap_derive/src/utils
7// This file was copied without modification.
8// It's an utilities file and not all function may be used in our project.
9// This is why we allow dead code.
10#![allow(dead_code)]
11
12use std::iter;
13
14pub fn extract_doc_comment(attrs: &[syn::Attribute]) -> Vec<String> {
15    // multiline comments (`/** ... */`) may have LFs (`\n`) in them,
16    // we need to split so we could handle the lines correctly
17    //
18    // we also need to remove leading and trailing blank lines
19    let mut lines: Vec<_> = attrs
20        .iter()
21        .filter(|attr| attr.path().is_ident("doc"))
22        .filter_map(|attr| {
23            // non #[doc = "..."] attributes are not our concern
24            // we leave them for rustc to handle
25            match &attr.meta {
26                syn::Meta::NameValue(syn::MetaNameValue {
27                    value:
28                        syn::Expr::Lit(syn::ExprLit {
29                            lit: syn::Lit::Str(s),
30                            ..
31                        }),
32                    ..
33                }) => Some(s.value()),
34                _ => None,
35            }
36        })
37        .skip_while(|s| is_blank(s))
38        .flat_map(|s| {
39            let lines = s
40                .split('\n')
41                .map(|s| {
42                    // remove one leading space no matter what
43                    let s = s.strip_prefix(' ').unwrap_or(s);
44                    s.to_owned()
45                })
46                .collect::<Vec<_>>();
47            lines
48        })
49        .collect();
50
51    while let Some(true) = lines.last().map(|s| is_blank(s)) {
52        lines.pop();
53    }
54
55    lines
56}
57
58pub fn format_doc_comment(
59    lines: &[String],
60    preprocess: bool,
61    force_long: bool,
62) -> (Option<String>, Option<String>) {
63    if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) {
64        let (short, long) = if preprocess {
65            let paragraphs = split_paragraphs(lines);
66            let short = paragraphs[0].clone();
67            let long = paragraphs.join("\n\n");
68            (remove_period(short), long)
69        } else {
70            let short = lines[..first_blank].join("\n");
71            let long = lines.join("\n");
72            (short, long)
73        };
74
75        (Some(short), Some(long))
76    } else {
77        let (short, long) = if preprocess {
78            let short = merge_lines(lines);
79            let long = force_long.then(|| short.clone());
80            let short = remove_period(short);
81            (short, long)
82        } else {
83            let short = lines.join("\n");
84            let long = force_long.then(|| short.clone());
85            (short, long)
86        };
87
88        (Some(short), long)
89    }
90}
91
92fn split_paragraphs(lines: &[String]) -> Vec<String> {
93    let mut last_line = 0;
94    iter::from_fn(|| {
95        let slice = &lines[last_line..];
96        let start = slice.iter().position(|s| !is_blank(s)).unwrap_or(0);
97
98        let slice = &slice[start..];
99        let len = slice
100            .iter()
101            .position(|s| is_blank(s))
102            .unwrap_or(slice.len());
103
104        last_line += start + len;
105
106        if len != 0 {
107            Some(merge_lines(&slice[..len]))
108        } else {
109            None
110        }
111    })
112    .collect()
113}
114
115fn remove_period(mut s: String) -> String {
116    if s.ends_with('.') && !s.ends_with("..") {
117        s.pop();
118    }
119    s
120}
121
122fn is_blank(s: &str) -> bool {
123    s.trim().is_empty()
124}
125
126fn merge_lines(lines: impl IntoIterator<Item = impl AsRef<str>>) -> String {
127    lines
128        .into_iter()
129        .map(|s| s.as_ref().trim().to_owned())
130        .collect::<Vec<_>>()
131        .join(" ")
132}
mithril_doc_derive/doc.rs

mithril_doc_derive/
doc.rs
