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 use std::iter;
7
extract_doc_comment(attrs: &[syn::Attribute]) -> Vec<String>8 pub fn extract_doc_comment(attrs: &[syn::Attribute]) -> Vec<String> {
9 use syn::Lit::*;
10 use syn::Meta::*;
11 use syn::MetaNameValue;
12
13 // multiline comments (`/** ... */`) may have LFs (`\n`) in them,
14 // we need to split so we could handle the lines correctly
15 //
16 // we also need to remove leading and trailing blank lines
17 let mut lines: Vec<_> = attrs
18 .iter()
19 .filter(|attr| attr.path.is_ident("doc"))
20 .filter_map(|attr| {
21 if let Ok(NameValue(MetaNameValue { lit: Str(s), .. })) = attr.parse_meta() {
22 Some(s.value())
23 } else {
24 // non #[doc = "..."] attributes are not our concern
25 // we leave them for rustc to handle
26 None
27 }
28 })
29 .skip_while(|s| is_blank(s))
30 .flat_map(|s| {
31 let lines = s
32 .split('\n')
33 .map(|s| {
34 // remove one leading space no matter what
35 let s = s.strip_prefix(' ').unwrap_or(s);
36 s.to_owned()
37 })
38 .collect::<Vec<_>>();
39 lines
40 })
41 .collect();
42
43 while let Some(true) = lines.last().map(|s| is_blank(s)) {
44 lines.pop();
45 }
46
47 lines
48 }
49
format_doc_comment( lines: &[String], preprocess: bool, force_long: bool, ) -> (Option<String>, Option<String>)50 pub fn format_doc_comment(
51 lines: &[String],
52 preprocess: bool,
53 force_long: bool,
54 ) -> (Option<String>, Option<String>) {
55 if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) {
56 let (short, long) = if preprocess {
57 let paragraphs = split_paragraphs(lines);
58 let short = paragraphs[0].clone();
59 let long = paragraphs.join("\n\n");
60 (remove_period(short), long)
61 } else {
62 let short = lines[..first_blank].join("\n");
63 let long = lines.join("\n");
64 (short, long)
65 };
66
67 (Some(short), Some(long))
68 } else {
69 let (short, long) = if preprocess {
70 let short = merge_lines(lines);
71 let long = force_long.then(|| short.clone());
72 let short = remove_period(short);
73 (short, long)
74 } else {
75 let short = lines.join("\n");
76 let long = force_long.then(|| short.clone());
77 (short, long)
78 };
79
80 (Some(short), long)
81 }
82 }
83
split_paragraphs(lines: &[String]) -> Vec<String>84 fn split_paragraphs(lines: &[String]) -> Vec<String> {
85 let mut last_line = 0;
86 iter::from_fn(|| {
87 let slice = &lines[last_line..];
88 let start = slice.iter().position(|s| !is_blank(s)).unwrap_or(0);
89
90 let slice = &slice[start..];
91 let len = slice
92 .iter()
93 .position(|s| is_blank(s))
94 .unwrap_or(slice.len());
95
96 last_line += start + len;
97
98 if len != 0 {
99 Some(merge_lines(&slice[..len]))
100 } else {
101 None
102 }
103 })
104 .collect()
105 }
106
remove_period(mut s: String) -> String107 fn remove_period(mut s: String) -> String {
108 if s.ends_with('.') && !s.ends_with("..") {
109 s.pop();
110 }
111 s
112 }
113
is_blank(s: &str) -> bool114 fn is_blank(s: &str) -> bool {
115 s.trim().is_empty()
116 }
117
merge_lines(lines: impl IntoIterator<Item = impl AsRef<str>>) -> String118 fn merge_lines(lines: impl IntoIterator<Item = impl AsRef<str>>) -> String {
119 lines
120 .into_iter()
121 .map(|s| s.as_ref().trim().to_owned())
122 .collect::<Vec<_>>()
123 .join(" ")
124 }
125