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)

[BA7LYA]

This problem still exist.

[emrekz]

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() {
...
}

[bobbrow]

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();

[JPHutchins]

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);

[bobbrow]

@JPHutchins from your screenshot it looks like you could benefit from #5773 as well. Did you add your 👍 to it yet?

[Delgan]

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();

@bobbrow This is great, I can confirm that it works very well, thanks!

I made some tests and discovered, however, that it breaks the rendering of code blocks (v1.21.6):

/**
 * @brief Hello there
 *
 * Hello again.
 *
 * ```cpp
 * int main() {
 *     std::cout << "Hello from code\n";
 *     return 1;
 * }
 *```
 */
void foo();

Should I open a new issue?

[bobbrow]

@Delgan, I can open it for you. Thanks for reporting it. This issue was supposed to have been closed with the release of 1.21.