Vscode-cpptools: Add support for doc comments

[Jackie-Yang]

How to write a function description like this

[sean-mcmanus]

Our extension doesn't currently implement the textDocument/signatureHelp which provides the function "doc-comments". We'll consider possibly adding that in a future release.

[guoqingaa]

Hastened to add this feature, the urgent need for this feature.

[guoqingaa]

Another year has passed, do not support this feature, to mention the depressed.
Add support for doc comments, the urgent need for this feature.

/* 
* a doc comments
*/

[sean-mcmanus]

XML doc comments is expected to be supported once signatureHelp is implemented via the IntelliSense engine. The current implementation doesn't support doc comments.

[guoqingaa]

Thank you for your reply, but c / c ++ function annotation style support is very necessary in the development of the input code and read the code a lot of help.
Xml style, such as C #

/// <summary>
/// Write the details of the function here
/// </ summary>
/// <param name = "out"> description of output parameters </ param>
/// <returns> description of return value </ returns>

c/c++ style, such as:

/** brief $ {cursor}
  *
  * Write the details of the function here
  * @param [in] (input parameter description, including the role of each parameter, the value and the relationship between parameters)
  * @param [out] (description of output parameters)
  * @return (description of return value)
  * @see (this function refers to other related functions, here as a link)
  * @note (description of the need to pay attention to the problem)
*/

[sean-mcmanus]

The C/C++ comment should still be supported, but it would appear as just a raw block comment as it does today in Visual Studio 2017 (the XML comments are parsed and the comment for the active param is shown). If you want better support for non-XML comments, it would probably be better addressed via a Visual Studio feedback site, such as https://visualstudio.uservoice.com/forums/121579-visual-studio-ide/category/30937-languages-c , since we're just borrowing their implementation. On 2nd thought, we actually might be able to parse the raw block comment to give the same experience as with XML comments. This won't be done for a while though.

[josesimoes]

Adding my vote for this. It would be really awesome.

Question (if this is possible to answer at this time): is the format above (mentioned by @guoqingaa) the one that is going to be supported?

[sean-mcmanus]

As I said in my previous post, all comments would be supported, but only the XML tags will be recognized specially, unless we decide to add additional parsing of the comments.

[guoqingaa]

please, the XML tags will be recognized specially at now, thank you.

[guoqingaa]

Nearly half a year, did not put this important function to support, it is really people can not understand, my God ah!

[Muny]

Any update on the status of the implementation of this functionality?

[sean-mcmanus]

@Muny- Unfortunately, it is not on our schedule yet. We listen to the survey feedback to prioritize work (e.g. C/Cpp: Take Survey) so our main focus right now is helping get IntelliSense configured correctly for users. In terms of new features this is about the 3rd most voted issue, when counted as a duplicate of https://github.com/Microsoft/vscode-cpptools/issues/658 .

[Misiu]

@sean-mcmanus thanks for update.
Do You know when this might be added? It isn't in March and April milestones.
Ideally there should be a roadmap with features You guys currently work on and with those that are in backlog and their order.
This would answer all those annoying questions (including mine 😄) when certain feature will be added.

[rei-vilo]

Please also consider the keywords and formatting of Doxygen _de facto_ standard.

References:

• Feature Request — Support for doxygen Documentation #658
• Doxygen website

[sean-mcmanus]

@Misiu I don't know when we'll start work on doc comments. We don't have a roadmap currently, but you could try asking @ronglums for one: https://blogs.msdn.microsoft.com/vcblog/2018/02/20/visual-studio-code-cc-extension-feb-2018-update/ . But VS Code itself doesn't offer much of a roadmap either, from what I can tell: https://github.com/Microsoft/vscode/milestones .

[ricardoboss]

Is this discussion still ongoing?

[rei-vilo]

I'm afraid this issue would have the same fate as https://github.com/Microsoft/vscode/issues/41309.

[bobbrow]

We are currently developing this feature. The first iteration will not have doxygen support, but that is also on our radar.

[aenima1891]

We are currently developing this feature. The first iteration will not have doxygen support, but that is also on our radar.

Doxygen support would be great!

[sean-mcmanus]

Our latest Insiders vsix has doc comments (no extra support for doxygen though): https://github.com/Microsoft/vscode-cpptools/releases . If you're using VS Code Insiders or have http.proxySupport not set to "off", you might not get the 0.21.0-insiders2 update automatically. And it doesn't work for comments on the right-side: https://github.com/Microsoft/vscode-cpptools/issues/2936 .

[zupalex]

As I said in my previous post, all comments would be supported, but only the XML tags will be recognized specially, unless we decide to add additional parsing of the comments.

Hi,

if I'm correct the doc comment support is now on the main branch. However I do not seem to be able to get the XML tag recognized. I followed the guidelines from this page but when I hover on the function I documented using the

tag, It displays everything as plain text, including the XML tags.

Did I misunderstand how XML tags are supposed to be parsed or am I missing something?

[bobbrow]

We don't currently do any special parsing of comment content yet. We will do doxygen first, but I don't think that there is an issue open for XML. Could you open one?

[sean-mcmanus]

@zupalex I moved the XML issue to https://github.com/Microsoft/vscode-cpptools/issues/3097.