GNOME Bugzilla – Bug 675766
Multiline Comment Blocks
Last modified: 2012-11-18 11:12:57 UTC
Multiline comment blocks inside functions don't behave as expected when inserted into the body of a function / method. I have not performed exhaustive tests of this issue, but, for example, the comment block: class test { void X() { /// Required comment /** Test comment: - Stuff1 @f$ x @f$ - Stuff2 @f$ y @f$ - Stuff 3 @f$ \mathbb{Z}_n^* @f$ */ } }; will render much different than this one: class test1 { void X() { /// Required comment /** * Test comment: * - Stuff1 @f$ x @f$ * - Stuff2 @f$ y @f$ * - Stuff 3 @f$ \mathbb{Z}_n^* @f$ */ } }; Things to note: - It renders badly if the intermediary "*"s are missing (and it does not display the formulas); - It does not reproduce if the big comment block is not preceded by some other (rendered) comment; - It messes up even if I use /// before every line of the comment block. The only version that seems to work properly is the one with the intermediary "*"s; - It's annoying, because intermediary "*"s are redundant and not every text editor adds them automatically.
Some tab characters messed up the code formatting when I submitted the bug. Here is the properly indented code (I hope): class test { void X() { /// Temporary variable /** Test comment: - Stuff1 @f$ bla1 @f$ - Stuff2 @f$ bla2 @f$ - Stuff 3 @f$ teeeeest @f$ */ } }; class test1 { void X() { /// Temporary variable /** * Test comment: * - Stuff1 @f$ bla1 @f$ * - Stuff2 @f$ bla2 @f$ * - Stuff 3 @f$ teeeeest @f$ */ } };
Can you please attach the example along with the config file in a zip or tar. That ways the tabs/spaces are preserved. Note that intermixing tabs and spaces requires TAB_SIZE to be properly set. Maybe that is part of the problem?
Created attachment 213767 [details] Test files meant to illustrate the described issue
Hi Dimitri, I don't think that TAB_SIZE is the issue here. Please find attached an archive containing examples with (more or less) consistent formatting. You will find several code blocks inside, meant to illustrate multiple issues that I discovered. I hope this helps. Best regards, Mihai Todor
Hi Mihai, Looking at your example, most issues come from Markdown support. See http://www.doxygen.org/markdown.html Try setting MARKDOWN_SUPPORT to NO and you'll see that you get the old behavior back. I'll have a look if any of your examples should have worked taking the Markdown rules into account.
Hi Dimitri, Thank you for investigating and clarifying this issue. While, indeed, the main issue that I reported is caused by markdown, I prefer to use the workarounds than to drop the markdown support completely. Perhaps, in the future, the integration will have fewer issues.
Confirmed. The fix for 679331 also solves these issues, so I'll mark this as duplicate. *** This bug has been marked as a duplicate of bug 679331 ***