ide_db/
rust_doc.rs

1//! Rustdoc specific doc comment handling
2
3use crate::documentation::Documentation;
4
5// stripped down version of https://github.com/rust-lang/rust/blob/392ba2ba1a7d6c542d2459fb8133bebf62a4a423/src/librustdoc/html/markdown.rs#L810-L933
6pub fn is_rust_fence(s: &str) -> bool {
7    let mut seen_rust_tags = false;
8    let mut seen_other_tags = false;
9
10    let tokens = s.trim().split([',', ' ', '\t']).map(str::trim).filter(|t| !t.is_empty());
11
12    for token in tokens {
13        match token {
14            "should_panic" | "no_run" | "ignore" | "allow_fail" => {
15                seen_rust_tags = !seen_other_tags
16            }
17            "rust" => seen_rust_tags = true,
18            "test_harness" | "compile_fail" => seen_rust_tags = !seen_other_tags || seen_rust_tags,
19            x if x.starts_with("edition") => {}
20            x if x.starts_with('E') && x.len() == 5 => {
21                if x[1..].parse::<u32>().is_ok() {
22                    seen_rust_tags = !seen_other_tags || seen_rust_tags;
23                } else {
24                    seen_other_tags = true;
25                }
26            }
27            _ => seen_other_tags = true,
28        }
29    }
30
31    !seen_other_tags || seen_rust_tags
32}
33
34const RUSTDOC_FENCES: [&str; 2] = ["```", "~~~"];
35
36pub fn format_docs(src: &Documentation) -> String {
37    format_docs_(src.as_str())
38}
39
40fn format_docs_(src: &str) -> String {
41    let mut processed_lines = Vec::new();
42    let mut in_code_block = false;
43    let mut is_rust = false;
44
45    for mut line in src.lines() {
46        if in_code_block && is_rust && code_line_ignored_by_rustdoc(line) {
47            continue;
48        }
49
50        if let Some(header) = RUSTDOC_FENCES.into_iter().find_map(|fence| line.strip_prefix(fence))
51        {
52            in_code_block ^= true;
53
54            if in_code_block {
55                is_rust = is_rust_fence(header);
56
57                if is_rust {
58                    line = "```rust";
59                }
60            }
61        }
62
63        if in_code_block {
64            let trimmed = line.trim_start();
65            if is_rust && trimmed.starts_with("##") {
66                line = &trimmed[1..];
67            }
68        }
69
70        processed_lines.push(line);
71    }
72    processed_lines.join("\n")
73}
74
75fn code_line_ignored_by_rustdoc(line: &str) -> bool {
76    let trimmed = line.trim();
77    trimmed == "#" || trimmed.starts_with("# ") || trimmed.starts_with("#\t")
78}
79
80#[cfg(test)]
81mod tests {
82    use super::*;
83
84    #[test]
85    fn test_format_docs_adds_rust() {
86        let comment = "```\nfn some_rust() {}\n```";
87        assert_eq!(format_docs_(comment), "```rust\nfn some_rust() {}\n```");
88    }
89
90    #[test]
91    fn test_format_docs_handles_plain_text() {
92        let comment = "```text\nthis is plain text\n```";
93        assert_eq!(format_docs_(comment), "```text\nthis is plain text\n```");
94    }
95
96    #[test]
97    fn test_format_docs_handles_non_rust() {
98        let comment = "```sh\nsupposedly shell code\n```";
99        assert_eq!(format_docs_(comment), "```sh\nsupposedly shell code\n```");
100    }
101
102    #[test]
103    fn test_format_docs_handles_rust_alias() {
104        let comment = "```ignore\nlet z = 55;\n```";
105        assert_eq!(format_docs_(comment), "```rust\nlet z = 55;\n```");
106    }
107
108    #[test]
109    fn test_format_docs_handles_complex_code_block_attrs() {
110        let comment = "```rust,no_run\nlet z = 55;\n```";
111        assert_eq!(format_docs_(comment), "```rust\nlet z = 55;\n```");
112    }
113
114    #[test]
115    fn test_format_docs_handles_error_codes() {
116        let comment = "```compile_fail,E0641\nlet b = 0 as *const _;\n```";
117        assert_eq!(format_docs_(comment), "```rust\nlet b = 0 as *const _;\n```");
118    }
119
120    #[test]
121    fn test_format_docs_skips_comments_in_rust_block() {
122        let comment =
123            "```rust\n # skip1\n# skip2\n#stay1\nstay2\n#\n #\n   #    \n #\tskip3\n\t#\t\n```";
124        assert_eq!(format_docs_(comment), "```rust\n#stay1\nstay2\n```");
125    }
126
127    #[test]
128    fn test_format_docs_does_not_skip_lines_if_plain_text() {
129        let comment =
130            "```text\n # stay1\n# stay2\n#stay3\nstay4\n#\n #\n   #    \n #\tstay5\n\t#\t\n```";
131        assert_eq!(
132            format_docs_(comment),
133            "```text\n # stay1\n# stay2\n#stay3\nstay4\n#\n #\n   #    \n #\tstay5\n\t#\t\n```",
134        );
135    }
136
137    #[test]
138    fn test_format_docs_keeps_comments_outside_of_rust_block() {
139        let comment = " # stay1\n# stay2\n#stay3\nstay4\n#\n #\n   #    \n #\tstay5\n\t#\t";
140        assert_eq!(format_docs_(comment), comment);
141    }
142
143    #[test]
144    fn test_format_docs_preserves_newlines() {
145        let comment = "this\nis\nmultiline";
146        assert_eq!(format_docs_(comment), comment);
147    }
148
149    #[test]
150    fn test_code_blocks_in_comments_marked_as_rust() {
151        let comment = r#"```rust
152fn main(){}
153```
154Some comment.
155```
156let a = 1;
157```"#;
158
159        assert_eq!(
160            format_docs_(comment),
161            "```rust\nfn main(){}\n```\nSome comment.\n```rust\nlet a = 1;\n```"
162        );
163    }
164
165    #[test]
166    fn test_code_blocks_in_comments_marked_as_text() {
167        let comment = r#"```text
168filler
169text
170```
171Some comment.
172```
173let a = 1;
174```"#;
175
176        assert_eq!(
177            format_docs_(comment),
178            "```text\nfiller\ntext\n```\nSome comment.\n```rust\nlet a = 1;\n```"
179        );
180    }
181
182    #[test]
183    fn test_format_docs_handles_escape_double_hashes() {
184        let comment = r#"```rust
185let s = "foo
186## bar # baz";
187```"#;
188
189        assert_eq!(format_docs_(comment), "```rust\nlet s = \"foo\n# bar # baz\";\n```");
190    }
191
192    #[test]
193    fn test_format_docs_handles_double_hashes_non_rust() {
194        let comment = r#"```markdown
195## A second-level heading
196```"#;
197        assert_eq!(format_docs_(comment), "```markdown\n## A second-level heading\n```");
198    }
199}
ide_db/rust_doc.rs

ide_db/
rust_doc.rs
