crates/rust-analyzer/src/markdown.rs

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