Search code examples
c++visual-studio-codeintellisense

Line breaks are not preserved following @brief and similar Doxygen keywords in the VS Code hover info with the Cpptools extension

How do I correctly apply line breaks in a documentation comment so the effects will be displayed appropriately in the hover info widget (mouse hover)? I'm currently not looking to generate any HTML or page documents.

C/C++ Extension Version: v1.15.4

Screenshots:

enter image description here enter image description here

In the first screenshot (the one on the left), all whitespaces are treated as a single space. The second screenshot takes into account the implicit newline as long as no @ keywords are used.

I've tried using multiple @brief lines and tried explicitly adding \n characters but to no avail.

Code:

/**
    @brief 
        Function # 1.
        Newline not working.
*/
void foo(int) {}

int main()
{
    foo(1);
    return 0;
}
Solution

  • This was a known issue. See New lines are removed from docstrings if prefixed by "@brief" Doxygen style #10039. This issue ticket in the Cpptools VS Code extension was blocked by changes in the software powering its server side: Avoid converting newlines into spaces in Doxygen "brief" comments, which was in the backlog since October 2022.

    It is fixed in 1.21.1 pre-release (source). An empty line will be interpreted as a paragraph break.