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.