vscode-cpptools
vscode-cpptools copied to clipboard
microsoft
New lines are removed from docstrings if prefixed by "@brief" Doxygen style
Environment
- OS and version: Ubutnu 20.04
- VS Code: 1.72.2
- C/C++ extension: v1.12.4
- OS and version of remote machine (if applicable): Ubuntu 20.04 (dev container)
- GDB / LLDB version: N/A
Bug Summary and Steps to Reproduce
Bug Summary:
When a docstrings starts with @brief (which is a Doxygen convention), then newlines are ignored. This is not very convenient, because the @brief should appear on the first line and detailed description on following blocks.
/**
* @brief A brief description.
*
* Detailed description starts here.
*/
void foobar() {}
With @brief:
Without @brief (expected):
Debugger Configurations
N/A
Debugger Logs
N/A
Other Extensions
No response
Additional Information
No response
It seems it's a regression, it was already fixed with:
- https://github.com/microsoft/vscode-cpptools/issues/5741
It's not a regression -- the fix was to turn the newline into a space.
This was opened on VS at https://developercommunity.visualstudio.com/t/Tooltips-are-not-showing-doxygen-comment/10087897 . They closed it as "not a bug". You could try filing a feature request.
@sean-mcmanus Indeed, sorry for calling this a regression. I thought it worked some times ago, I must have been dreaming.
Following your advice, I opened a "feature request" ticket here: Avoid converting newlines into spaces in Doxygen "brief" comments (#10178887). :+1:
I have realised its not just the @brief that's causing the problem... Instead, it is any type of Doxygen specific keyword (i.e. @param, @note, @return, @returns). Without any keywords, newlines are preserved.
Example with no Doxygen keywords:
Example with Doxygen keyword used:
Related on Stack Overflow: Line breaks are not preserved following @brief and similar Doxygen keywords in the VS Code hover info with the Cpptools extension.
@sean-mcmanus Indeed, sorry for calling this a regression. I thought it worked some times ago, I must have been dreaming.
Following your advice, I opened a "feature request" ticket here: Avoid converting newlines into spaces in Doxygen "brief" comments (#10178887). 👍
Make sure to upvote here: https://developercommunity.visualstudio.com/t/Avoid-converting-newlines-into-spaces-in/10178887
IMO it's a bug.
An annoying workaround (setup process and only one new line) until this is pushed to release is to use the @detail command to get a line break between the brief and description. Make sure to enable the details tag in Extensions -> C/C++ -> Code Documentation -> Section Tags (C_Cpp.doxygen.sectionTags)
An another workaround which may helps but has not regular font style.
/**
* @brief #### Test description 1
* @brief #### Test description 2
* @brief #### Test description 3
* @param x integer
* @param y integer
*/
void testFunction() {
...
}
I believe this is fixed starting in 1.21.1 pre-release (soon to be published). We will interpret an empty line as a paragraph break.
/**
* @brief Hello there
*
* Hello again
*/
void foo();
I believe this is fixed starting in 1.21.1 pre-release (soon to be published). We will interpret an empty line as a paragraph break.
/** * @brief Hello there * * Hello again */ void foo();
It's fixed! I'm crying. 🥲
/**
* @brief Encode the response into a packet.
*
* Newlines work! If there's a blank line first!
* @param response The response to encode.
* @param [out] packet Pointer to the output packet.
* @return Error code.
*/
int api_encode(struct api_response const * response, union api_packet * out_packet);
@JPHutchins from your screenshot it looks like you could benefit from #5773 as well. Did you add your 👍 to it yet?