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