Leave the non-recognized doxygen commands in comments

[sean-mcmanus]

It is possible to leave the commands that are not being converted? We use \note, \pre, and \post. The current behavior is that they don't show up in the tool tip at all.

Originally posted by @jhortenstine in #658 (comment)

[sean-mcmanus]

@jhortenstine I think the intent is to avoid showing "too much" info, but it seems like only specifically handled commands should be omitted that are deemed to be "too much", instead of omitting all unrecognized commands by default.

The fact that we don't show \short comments (equivalent to \brief) is an example where were are definitely omitting comments where we should not be (not sure if \note, \pre, and \post fall into that case or not).

I filed a VS issue at https://developercommunity.visualstudio.com/content/problem/1093392/cc-doxygen-comments-are-not-shown-for-commands-tha.html

[jhortenstine]

I am curious on what "too much" info is (not saying it is wrong design). I thought the previous behavior was just to display the entire comment (at least I could not make it drop text).

Thank you for filing this issue.

[sean-mcmanus]

Yes, the previous behavior displayed the entire raw comment formatted as text. I'm not sure which commands would count as "too much" info -- that's just what I was told by the VS VC team when I hit the same issue, but I was using @details so I didn't realize the hiding was being applied to all unrecognized commands. Hopefully, they could document what the expected behavior is in regards to which doxygen commands are shown specially, shown as plain text, or not shown.

[michelleangela]

Just to clarify, the expected behavior for displaying non-Doxygen comments and Doxygen comments in tooltips are different, so I don't think this is a regression for Doxygen support feature.

Simple text comment (without Doxygen tags/commands) should still display the entire text as there are no text to parse by tags.

Doxygen comments currently display info in the tooltips from the following tags:

• brief
• param
• return
• exception
• deprecated

Edit: perhaps this is a feature request to display additional Doxygen tags, like add a settings to specify which tags to display.

[bobbrow]

Does VS Code support collapsible sections in tooltips? If so, we could potentially place the raw comment in there as a stop gap.

[jhortenstine]

@michelleangela This is not a feature request to display additional Doxygen tags. This is a request to see all the text from the comment.

For example:
/** Initiates a time warp.
@param[in] time Unix time
@pre Must be going at least 88 mph.
*/
The current Doxygen pop-up will not show the @pre line at all. I would prefer if the text was there somehow. I am completely fine with it just copying the text.

[michelleangela]

@jhortenstine

Thanks for clarifying and providing additional info. We've decided to address this issue by providing settings to allow users to choose between the following options:

• Display simplified Doxygen comments --> displays comments from a few selected tags.
• Display complete Doxygen comments --> displays all comments from all tags, and comments at the top without tags is considered as "brief" comments.

These options will be applied to the hover and auto-complete tooltips. It will not be applied to the signature help tooltip, which is specifically designed to only show the comment of the current active parameter (whichever parameter the cursor is on), and is followed by brief comment.

Since this issue is about the presentation layer, it is not an issue against the Doxygen parser that is also used by Visual Studio. So this issue is not dependent on the one filed for Visual Studio at https://developercommunity.visualstudio.com/content/problem/1093392/cc-doxygen-comments-are-not-shown-for-commands-tha.html

[michelleangela]

Re-opening until it is released in 0.29.0

[sean-mcmanus]

With https://github.com/microsoft/vscode-cpptools/releases/tag/0.29.0-insiders2 you can set the C_Cpp.simplifyStructuredComments setting to false to show all comments. Let us know if you have any additional feedback on that, in particular, the styling changes.

[jhortenstine]

The only thing I saw missing was the param's "in", "out", or "in, out".
The styling was nice. It allows me to find the parameters quickly and helped distinguish between the commands.

Edit: The in/out is much less important than the fix you have. Thank you for providing a fix.

[BillDenton]

@sean-mcmanus The option shows as "C_Cpp.simplifyStructuredComments" not "C_Cpp.simplyStructuredComments"
It is a bit intermittent as to when it works or not. I think that may be more general problems with the C/C++ extension as it still (nearly always) consumes a core all the time. Also, I don't have compile json database (waiting for scons to generate it and getting our scons upgraded).
Like the format, but would have liked to see the "out" and "in,out". We are omitting the "in" for input only parameters.
I notice if there isn't a description for the parameter then the parameter isn't shown:
/**

• Brief description which is shown.
• @param ParamOne Parameter one which is shown.
• @param ParamTwo
  */
  The "brief description" is shown. "ParamOne" shows. "ParamTwo" not shown. If none of the parameters has descriptions then nothing shows. I think all our functions have @param (because we check Doxygen during submission), but don't all have descriptions.

[bobbrow]

The option shows as "C_Cpp.simplifyStructuredComments" not "C_Cpp.simplyStructuredComments"

I corrected the typo.

[michelleangela]

Created a feature request on Visual Studio to support '['dir']' of command Doxygen \param so that [in] or [out] are also parsed.
https://developercommunity.visualstudio.com/content/problem/1111522/support-dir-optional-attribute-of-doxygen-param.html.

GitHub issue that's tracking request:
#5773

[michelleangela]

The fix for this is in progress and will be included in release of 0.29.0.

I notice if there isn't a description for the parameter then the parameter isn't shown:
/**

• Brief description which is shown.
• @param ParamOne Parameter one which is shown.
• @param ParamTwo
  */
  The "brief description" is shown. "ParamOne" shows. "ParamTwo" not shown. If none of the parameters has descriptions then nothing shows. I think all our functions have @param (because we check Doxygen during submission), but don't all have descriptions.

[sean-mcmanus]

Can this issue be closed (with 0.29.0) or were there additional feedback to follow up on and open new issues for?

[michelleangela]

This can be closed. I created new issues of the other issues.