Repository navigation
Leave the non-recognized doxygen commands in comments #5706
Description
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)
Activity
sean-mcmanus commentedon Jun 26, 2020
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 commentedon Jun 26, 2020
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 commentedon Jun 26, 2020
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 commentedon Jun 29, 2020
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:
Edit: perhaps this is a feature request to display additional Doxygen tags, like add a settings to specify which tags to display.
bobbrow commentedon Jun 29, 2020
Does VS Code support collapsible sections in tooltips? If so, we could potentially place the raw comment in there as a stop gap.
jhortenstine commentedon Jun 30, 2020
Michelle Matias (@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
Petrus Repo (@pre) Must be going at least 88 mph.
*/
The current Doxygen pop-up will not show the Petrus Repo (@pre) line at all. I would prefer if the text was there somehow. I am completely fine with it just copying the text.
11 remaining items
michelleangela commentedon Jul 7, 2020
Re-opening until it is released in 0.29.0
sean-mcmanus commentedon Jul 9, 2020
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 commentedon Jul 9, 2020
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 commentedon Jul 11, 2020
Sean McManus (@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:
/**
*/
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 commentedon Jul 13, 2020
I corrected the typo.
michelleangela commentedon Jul 13, 2020
Created a feature request on Visual Studio to support '['dir']' of command Doxygen
\paramso 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 commentedon Jul 13, 2020
The fix for this is in progress and will be included in release of 0.29.0.
sean-mcmanus commentedon Jul 16, 2020
Can this issue be closed (with 0.29.0) or were there additional feedback to follow up on and open new issues for?
michelleangela commentedon Jul 16, 2020
This can be closed. I created new issues of the other issues.