Auto merge of #14866 - AndreasBackx:feature/doc-comments-markdown, r=…

…Veykril

[editors/code] add markdown syntax highlighting to doc comments

_This is a continuation of microsoft/vscode#169956 and dustypomerleau/rust-syntax#37 (that repo is no longer maintained: dustypomerleau/rust-syntax#39 (comment)). The VS Code team seemed to prefer this being inside of an extension._

This adds Markdown highlighting to doc comment lines and blocks. Currently it is thus regarded both as a comment and as Markdown which leads to normally foreground text being in the colour of the comment and the rest highlighted like Markdown or its own embedded languages in code blocks.

![image](https://github.com/rust-lang/rust-analyzer/assets/1593486/c84f2e83-faea-47ca-853d-3728a07b2b66)

![image](https://github.com/rust-lang/rust-analyzer/assets/1593486/f4191425-32cd-451c-ae3a-29a0970ce7a2)

Block comments are supported, but currently not when there is a `*` at the start of the line:
![image](https://github.com/rust-lang/rust-analyzer/assets/1593486/ce3b58d5-9dca-4376-bffe-4f5a54acbe37)
![image](https://github.com/rust-lang/rust-analyzer/assets/1593486/b73a5ee6-a178-4aef-a0e4-3d75e4e7d8e5)

I'm not entirely sure if I can easily fix this, I'd need to find a way to make the content ignore the `*`. Though I'm unsure if it's important as there are [conventions against using block comments](
https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#use-line-comments) and using them without `*` does work. All of this TextMate grammar is so hard to find documentation on that _honestly_ I'd just not want to support this considering the effort.

Let me know what everyone thinks of this being in rust-analyzer. I've personally found it hard to write large amounts of Rust documentation due to the lack of Markdown syntax highlighting.

Also, thank you `@adenine-dev` as well for making this available in the interim and your enthousiasm. Wanted to get this PR out sooner, but life gets in the way.

editors/code/package.json

@@ -1562,6 +1562,16 @@
                 "language": "ra_syntax_tree",
                 "scopeName": "source.ra_syntax_tree",
                 "path": "ra_syntax_tree.tmGrammar.json"
+            },
+            {
+                "scopeName": "rustdoc.markdown.injection",
+                "path": "rustdoc.markdown.injection.tmGrammar.json",
+                "injectTo": [
+                    "source.rust"
+                ],
+                "embeddedLanguages": {
+                    "meta.embedded.block.markdown": "text.html.markdown"
+                }
             }
         ],
         "problemMatchers": [

editors/code/rustdoc.markdown.injection.tmGrammar.json

@@ -0,0 +1,36 @@
+{
+    "scopeName": "rustdoc.markdown.injection",
+    "injectionSelector": "L:source.rust",
+    "patterns": [
+        {
+            "include": "#doc-comment-line"
+        },
+        {
+            "include": "#doc-comment-block"
+        }
+    ],
+    "repository": {
+        "doc-comment-line": {
+            "name": "comment.line.documentation.rust",
+            "begin": "^\\s*//(/|!)",
+            "while": "^\\s*//(/|!)",
+            "contentName": "meta.embedded.block.markdown",
+            "patterns": [
+                {
+                    "include": "text.html.markdown"
+                }
+            ]
+        },
+        "doc-comment-block": {
+            "name": "comment.block.documentation.rust",
+            "begin": "/\\*(\\*|!)",
+            "end": "\\s*\\*/",
+            "contentName": "meta.embedded.block.markdown",
+            "patterns": [
+                {
+                    "include": "text.html.markdown"
+                }
+            ]
+        }
+    }
+}