Mark documentation comment blocks as Markdown. #37
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bors
added a commit
to rust-lang/rust-analyzer
that referenced
this pull request
May 24, 2023
…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.   Block comments are supported, but currently not when there is a `*` at the start of the line:   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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds support for marking the content inside of a doc comment as markdown. Additionally the following identifiers are marked as documentation blocks as well:
//!/*!These were previously identified as the double slash / non-doc variant. These are defined in the Rust spec: https://doc.rust-lang.org/reference/comments.html
Examples of how this looks in VS Code:
It still defaults to the comment foreground colour for codeblocks in VS Code, though my guess is that this is a VS Code issue? Might even be an issue of my own theme.
Looking at the default theme, it definitely seems like an issue for my theme:
This comes from my original issue microsoft/vscode#169676 and I hope to sync this to the PR for VS Code as well: microsoft/vscode#169956. #20 also suggested this feature.
Let me know what you think. 😃