crates/rust-analyzer/src/markdown.rs

   1 //! Transforms markdown
   2
   3 const RUSTDOC_FENCE: &str = "```";
   4 const RUSTDOC_CODE_BLOCK_ATTRIBUTES_RUST_SPECIFIC: &[&str] = &[
   5     "",
   6     "rust",
   7     "should_panic",
   8     "ignore",
   9     "no_run",
  10     "compile_fail",
  11     "edition2015",
  12     "edition2018",
  13     "edition2021",
  14 ];
  15
  16 pub(crate) fn format_docs(src: &str) -> String {
  17     let mut processed_lines = Vec::new();
  18     let mut in_code_block = false;
  19     let mut is_rust = false;
  20
  21     for mut line in src.lines() {
  22         if in_code_block && is_rust && code_line_ignored_by_rustdoc(line) {
  23             continue;
  24         }
  25
  26         if let Some(header) = line.strip_prefix(RUSTDOC_FENCE) {
  27             in_code_block ^= true;
  28
  29             if in_code_block {
  30                 is_rust =
  31                     header.split(',').all(|sub| is_rust_specific_code_block_attribute(sub.trim()));
  32
  33                 if is_rust {
  34                     line = "```rust";
  35                 }
  36             }
  37         }
  38
  39         processed_lines.push(line);
  40     }
  41     processed_lines.join("\n")
  42 }
  43
  44 fn is_rust_specific_code_block_attribute(attr: &str) -> bool {
  45     if RUSTDOC_CODE_BLOCK_ATTRIBUTES_RUST_SPECIFIC.contains(&attr) {
  46         return true;
  47     }
  48     attr.starts_with('E') && attr.len() == 5 && attr[1..].parse::<u32>().is_ok()
  49 }
  50
  51 fn code_line_ignored_by_rustdoc(line: &str) -> bool {
  52     let trimmed = line.trim();
  53     trimmed == "#" || trimmed.starts_with("# ") || trimmed.starts_with("#\t")
  54 }
  55
  56 #[cfg(test)]
  57 mod tests {
  58     use super::*;
  59
  60     #[test]
  61     fn test_format_docs_adds_rust() {
  62         let comment = "```\nfn some_rust() {}\n```";
  63         assert_eq!(format_docs(comment), "```rust\nfn some_rust() {}\n```");
  64     }
  65
  66     #[test]
  67     fn test_format_docs_handles_plain_text() {
  68         let comment = "```text\nthis is plain text\n```";
  69         assert_eq!(format_docs(comment), "```text\nthis is plain text\n```");
  70     }
  71
  72     #[test]
  73     fn test_format_docs_handles_non_rust() {
  74         let comment = "```sh\nsupposedly shell code\n```";
  75         assert_eq!(format_docs(comment), "```sh\nsupposedly shell code\n```");
  76     }
  77
  78     #[test]
  79     fn test_format_docs_handles_rust_alias() {
  80         let comment = "```ignore\nlet z = 55;\n```";
  81         assert_eq!(format_docs(comment), "```rust\nlet z = 55;\n```");
  82     }
  83
  84     #[test]
  85     fn test_format_docs_handles_complex_code_block_attrs() {
  86         let comment = "```rust,no_run\nlet z = 55;\n```";
  87         assert_eq!(format_docs(comment), "```rust\nlet z = 55;\n```");
  88     }
  89
  90     #[test]
  91     fn test_format_docs_handles_error_codes() {
  92         let comment = "```compile_fail,E0641\nlet b = 0 as *const _;\n```";
  93         assert_eq!(format_docs(comment), "```rust\nlet b = 0 as *const _;\n```");
  94     }
  95
  96     #[test]
  97     fn test_format_docs_skips_comments_in_rust_block() {
  98         let comment =
  99             "```rust\n # skip1\n# skip2\n#stay1\nstay2\n#\n #\n   #    \n #\tskip3\n\t#\t\n```";
 100         assert_eq!(format_docs(comment), "```rust\n#stay1\nstay2\n```");
 101     }
 102
 103     #[test]
 104     fn test_format_docs_does_not_skip_lines_if_plain_text() {
 105         let comment =
 106             "```text\n # stay1\n# stay2\n#stay3\nstay4\n#\n #\n   #    \n #\tstay5\n\t#\t\n```";
 107         assert_eq!(
 108             format_docs(comment),
 109             "```text\n # stay1\n# stay2\n#stay3\nstay4\n#\n #\n   #    \n #\tstay5\n\t#\t\n```",
 110         );
 111     }
 112
 113     #[test]
 114     fn test_format_docs_keeps_comments_outside_of_rust_block() {
 115         let comment = " # stay1\n# stay2\n#stay3\nstay4\n#\n #\n   #    \n #\tstay5\n\t#\t";
 116         assert_eq!(format_docs(comment), comment);
 117     }
 118
 119     #[test]
 120     fn test_format_docs_preserves_newlines() {
 121         let comment = "this\nis\nmultiline";
 122         assert_eq!(format_docs(comment), comment);
 123     }
 124
 125     #[test]
 126     fn test_code_blocks_in_comments_marked_as_rust() {
 127         let comment = r#"```rust
 128 fn main(){}
 129 ```
 130 Some comment.
 131 ```
 132 let a = 1;
 133 ```"#;
 134
 135         assert_eq!(
 136             format_docs(comment),
 137             "```rust\nfn main(){}\n```\nSome comment.\n```rust\nlet a = 1;\n```"
 138         );
 139     }
 140
 141     #[test]
 142     fn test_code_blocks_in_comments_marked_as_text() {
 143         let comment = r#"```text
 144 filler
 145 text
 146 ```
 147 Some comment.
 148 ```
 149 let a = 1;
 150 ```"#;
 151
 152         assert_eq!(
 153             format_docs(comment),
 154             "```text\nfiller\ntext\n```\nSome comment.\n```rust\nlet a = 1;\n```"
 155         );
 156     }
 157 }