New lines are removed from docstrings if prefixed by "@brief" Doxygen style

[Delgan]

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

[Delgan]

It seems it's a regression, it was already fixed with:

• Comment lines without Doxygen tags is not parsed correctly #5741

[sean-mcmanus]

It's not a regression -- the fix was to turn the newline into a space.

[sean-mcmanus]

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.

[Delgan]

@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). 👍

[dimsanius]

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:

[starball5]

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.

[JPHutchins]

@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.

[bastian2001]

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)