Markdown comment support for tooltip display of hover

[DeadRabbits307]

Type: LanguageService

Like the support for doxygen documentation (#658) the support for Markdown would be nice. Like in Rust:

[sean-mcmanus]

VS Code inherently supports markdown in doc comments, but we added code to explicitly disable/escape it for code that has comments that are not intended to be interpreted as markdown. We'd need to add a setting to re-enable the markdown.

[Leedehai]

Following @sean-mcmanus's response above.. Where can we re-enable that in code? I was trying to tweak files in ~/.vscode/extensions/ms-vscode.cpptools-1.0.1 so I can render the comment in Markdown without having to wait for a new Cpptools release :) It looks we just need to delete the code that is used to "explicitly disable/escape" Markdown.

[sean-mcmanus]

The markdown escaping is done in our closed source cpptools process. I haven't looked into whether there's a way to undo the escaping via the open source TypeScript.

[ericdrobinson]

We'd need to add a setting to re-enable the markdown.

I was surprised that there isn't a way to get markdown formatting already. We use this feature in other languages to great effect. Would very much love to see it enabled in C/C++.

[bshoshany]

Hi @sean-mcmanus, I came here to request this exact same feature and found that it was already requested. It's been almost 2 years since this issue opened and more than a year since the last reply, I wonder if any progress has been made into enabling Markdown comments in C/C++? This would be extremely helpful in writing more meaningful and informative code documentation for my C++ libraries. Thanks!

[sean-mcmanus]

@bshoshany There hasn't been any progress yet. If you see this issue get assigned to a milestone then you could expect progress.

[bshoshany]

@sean-mcmanus, thank you so much for your quick reply. I understand that this is not a high-priority issue. However, from your post above, if I understand correctly, it sounds like allowing Markdown comments is a simple matter of re-enabling something that was disabled. If that is indeed the case, I wonder if perhaps you could consider putting this issue at a higher priority, since it is a low-effort fix?

[sean-mcmanus]

It looks like it would be a medium effort fix. There's problems with how to combine the cpp formatted comments with the markdown comments and how to deal with potential security issues with exposing links in the comments.

[bshoshany]

I see, thanks for explaining. I hope it gets implemented soon, as it would be a very helpful feature.

[pauljurczak]

how to deal with potential security issues with exposing links in the comments.

Ignore the links. Display them as a text.

[TomasVaner]

Waiting for this feature actually. Because if comments would support markdown, the issue with multiline comments becoming one line text in the tooltip would be resolved.
And I need multiline text in my documentation ;)

[bshoshany]

how to deal with potential security issues with exposing links in the comments.

Ignore the links. Display them as a text.

How about this: display them as links in a trusted folder, and as text in a restricted folder. Problem solved!

[Zingam]

I second that. I'd like markdown support and better Doxygen compatibility and more of the comment styles supported: qt, etc.

I'd like the same level of support as displayed on the screenshots.

[bblanchon]

how to deal with potential security issues with exposing links in the comments.

JavaScript displays URLs as clickable links.
Why would that be a security issue in C++ and not in JavaScript?

Besides, VS Code asks for confirmation before opening the link.

[sean-mcmanus]

@bblanchon Yeah, good point -- we had removed the links a long time ago before VS Code implemented the "external website" link feature for links.

[PoetaKodu]

The current hover preview of doc comments is very limited. There is no XML-style support. There is no Markdown support. Doxygen-style comment support is also limited.

This is extremely annoying when writing C++ code, where functions tend to have many overloads and even if you properly document them, you have to manually navigate to the declaration each time you use them.

I do not understand how this feature wasn't a priority for over 2 years now. It seems to be relatively easy to implement and the benefits would be huge. Adding inlay hints was a big step towards productivity and I think this should be the next one. Please consider it.

Edit:
Hover documentation preview is everything. In CLion you also get a link to the related cppreference article if you use a name from the standard library.

[sean-mcmanus]

@PoetaKodu FYI, two other reasons we escaped markdown in hover are #3441 (prevent undesired underscore symbols becoming bold) and #2937 (prevent newlines getting removed). However, it seems like we could add some special case code to deal with those cases.

[PoetaKodu]

What about other Markdown features: inline code, fenced code blocks, headings, links, etc.?

[starball5]

Related on Stack Overflow: Using C/C++ in VS Code, how can I create lists and tables within tooltip description of symbols?.

[joule19]

Found out that my issue of using HTML tags within doxygen-styled comments for C++ can be related to the issue discussed here. Any chance to have soon markdown support (including HTML) for tooltip display of hover? :-)

[sean-mcmanus]

@joule19 No, HTML would not be supported. Markdown is supported because that is what VS Code will process/render, i.e. I think VS Code itself would need to add support for that.

[michelleangela]

Fix available in pre-release https://github.com/microsoft/vscode-cpptools/releases/tag/v1.17.0.

[naksyl]

There is still space to improve. It looks like in section every new line is removed, every line trimmed and joind with space. Not usable:

• lists
• code blocks

/// ACTUAL - every section is paragraph                         | IDEAL - every section is markdown document
/// @brief This is a markdown test for doxygen hover            | @brief This is a markdown test for doxygen hover
///                                                             |
/// @details                                                    | @details
/// No way to to simple start new paragraph - only by duplicate | Simple way to to start new paragraph - by empty line
/// doxygen section                                             | doxygen section
///                                                             |
/// This paragraph is joined                                    | This paragraph is not joined
/// @details                                                    |
/// New paragraph                                               | New paragraph
/// @details                                                    |
/// Another paragraph                                           | Another paragraph
/// @details                                                    |
/// __Bold__ _italic_ `inline code` - works as expected         | __Bold__ _italic_ `inline code` - works as expected
///                                                             |
/// @details                                                    | Code block should be rendered render as actual block code
/// Code block is rendered render as inline code                |
/// even on it's own section                                    |
/// @details                                                    | ```c
/// ```c                                                        | puts("Hello World");
/// puts("Hello World");                                        | system("pause");
/// system("pause");                                            | ```
/// ```                                                         |
/// @note                                                       | @note                                               
/// Test markdown lists - again whole section is treated        | Test markdown lists - whole section is markdown document
/// as single paragraph                                         | as single paragraph                                 
/// @note                                                       |
/// - item1                                                     | - item1                                             
///    - subitem                                                |    - subitem                                        
/// - item 2                                                    | - item 2                                            
int variable;

[thekpaul]

@naksyl For the new line problem, there's a separate issue at #10039 with a VS "feature request" ticket for it open here. Apparently it's a "design choice" to show line breaks as spaces instead of actual new lines, regardless of how many new lines we use in between.

Code blocks also don't seem to be fully supported, but IIRC, if there's no explicit DOxygen tags inside the comment, the code block shows up in the same format as the actual body of the editor. This seems to be a similar behaviour to the new line problem, where, if we don't use DOxygen tags, the newlines are displayed as actual new lines instead of spaces.

My personal hunch is that, without DOxygen tags, the comments are rendered as regular comments with line breaks and code block formatting, but as soon as a DOxygen tag is introduced, those functionality are suppressed.

UPDATE: Got a screenshot of code blocks working if there aren't any DOxygen tags!

I suppose the astericks and underscore are shown with a preceding backslash as an escape sequence. If I add the backslash in the comment itself, the hover breaks at that character and doesn't show anything afterwards.

[naksyl]

Ok, I misunderstood this markdown feature. It works for plain comments (no doxygen tags) - even tables.

mea culpa

[michelleangela]

Fixed in release version https://github.com/microsoft/vscode-cpptools/releases/tag/v1.17.2.