crates/rust-analyzer/src/markdown.rs

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