crates/rust-analyzer/src/markdown.rs

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