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:

Comment lines without Doxygen tags is not parsed correctly #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 (@sean-mcmanus)

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

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 (@sean-mcmanus)

Sean McManus (@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.

Detail (@detail)

An annoying workaround (setup process and only one new line) until this is pushed to release is to use the Detail (@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)

This problem still exist.

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

JP Hutchins (@JPHutchins)

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

Bob Brown (@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();

Bob Brown (@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?

Delgan

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.

Navigation Menu

Repository navigation

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

Environment

Bug Summary and Steps to Reproduce

Debugger Configurations

Debugger Logs

Other Extensions

Additional Information

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Environment

Bug Summary and Steps to Reproduce

Debugger Configurations

Debugger Logs

Other Extensions

Additional Information

Activity

Delgan commented on Oct 20, 2022

sean-mcmanus commented on Oct 21, 2022

sean-mcmanus commented on Oct 21, 2022

Delgan commented on Oct 21, 2022

dimsanius commented on Dec 12, 2022

starball5 commented on Jun 14, 2023

JPHutchins commented on Jul 30, 2023

bastian2001 commented on Apr 12, 2024

ba7lya commented on Jul 5, 2024

emrekz commented on Jul 14, 2024

bobbrow commented on Jul 15, 2024

JPHutchins commented on Aug 2, 2024

bobbrow commented on Aug 2, 2024

Delgan commented on Oct 1, 2024

bobbrow commented on Oct 1, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions