\snippet{doc} tag in Doxygen v1.11 adds incorrect paragraph with a break before snippet text

[DCDEIE]

Describe the bug

Previously, the \snippet{doc} tag respected spacing in snippet text contained in .md files and in .dox files at the point where snippet tags were inserted. Now, there is a paragraph with a break inserted between the snippet tag and text or section titles before the snippet tag.

Screenshots

To Reproduce

test_snippet_spacing.zip

Expected behavior

There should be no extra space by default between the text before a snippet and the snippet text that is inserted at the time of compiling HTML Help, unless the user has specified this spacing.

• In the zip file to reproduce this issue, the section titled Testing snippets to show incorrect space inserted before snippet tag demonstrates this spacing issue.
• In the zip file to reproduce this issue, the section titled Testing snippets to show workaround to remove extra space before snippet tag shows how moving the snippet tag back to be in-line with the text directly before the snippet tag resolves this spacing issue in all cases except after a section title.

Version

• Doxygen v1.11
• Windows 10, 64-bit

[albert-github]

The problem looks like to be caused by the way the *.dox are created, they are as C source files created and the result of the doxygen -d commentcnv gives:

/**

\mainpage Testing snippets to show incorrect space inserted before snippet tag

\section ALL_SDKS_OVERVIEW Overview

This is the overview. Inserting a snippet next adds incorrect spacing before the snippet.

 \ilinebr \ifile "D:/speeltuin/issue_10935/test_snippet_spacing/dox/snippets/Snippets.md" \iline 1
 * \note This is snippet 1.
 *  \ilinebr \ifile "D:/speeltuin/issue_10935/test_snippet_spacing/dox/mainpage.dox" \iline 9

\subsection MAIN_INCL_COMPONENTS Included components

Note the * in front of some included lines.

When we would change the *.dox files in markdown files, i.e. just remove the /** and */ lines and set

EXTENSION_MAPPING = dox=md

The problem is gone.

I'm not sure whether this is to be qualified as bug or as usage.
@doxygen what do you think?

[DCDEIE]

Hi albert-github,

Thank you for your solution and input. This changed behaviour was introduced with v1.11. Prior to that, it worked without issue, so I would see your solution more as a viable workaround. However, it would be great to have the functionality as it was in previous versions, without the extra space before snippet text.

[albert-github]

The place where the handling of the \snippet{doc} (and \include{doc}) has changed for a better and easier handling.
The problem you face here is an unexpected side effect and I can imagine that it would be nice not to have to change your code.
A complicating factor is also the fact that you have a starting empty line in your snippet.

[DCDEIE]

Removing the empty starter line in the snippet does not change the behaviour. I removed the empty lines in the snippets and it didn’t change anything unfortunately. I initially hoped it was that easy to resolve by just removing the empty line in the snippet, but the issue seems to be from logic that is hard-coded somewhere.

[DCDEIE]

FYI, this issue was introduced with v1.11. I also installed v1.10 and this problem does not occur with the superfluous spacing in v1.10.

[albert-github]

The problem look to be the addition of the * that was done for the 1.11.0 version when having a /** type of comment, maybe this addition should be optional based on whether or not the \snippet{doc} line starts with a * or not.
@doxygen ?

[doxygen]

@albert-github Indeed, the * should have been there only if the comment block already had leading *'s to start with. I'll see what's wrong.

[doxygen]

@albert-github Looks like this is related to the fix for #10858. The extra '\n' added to the lineStr by this fix seems to be causing the extra whitespace.

If I remove it, the whitespace is gone:

$ git diff
diff --git a/src/commentcnv.l b/src/commentcnv.l
index 255a30dcc4..6e412cae63 100644
--- a/src/commentcnv.l
+++ b/src/commentcnv.l
@@ -1719,7 +1719,7 @@ static bool readIncludeFile(yyscan_t yyscanner,const QCString &inc,const QCStrin
     QCString oldRaiseLabel = yyextra->raiseLabel;
     yyextra->raiseLevel+=yyextra->raiseIncrement;
     yyextra->raiseLabel+=yyextra->raisePrefix;
-    lineNr--;
+    //lineNr--;
     QCString lineStr=" \\ilinebr \\ifile \""+absFileName+"\" \\iline " + std::to_string(lineNr);
     if (yyextra->raiseLevel>0)
     {
@@ -1729,9 +1729,9 @@ static bool readIncludeFile(yyscan_t yyscanner,const QCString &inc,const QCStrin
     {
       lineStr+=" \\iprefix \"" + yyextra->raiseLabel + "\"";
     }
-    copyToOutput(yyscanner,lineStr.view());
-    insertCommentStart(yyscanner);
-    lineStr="\n";
+    //copyToOutput(yyscanner,lineStr.view());
+    //insertCommentStart(yyscanner);
+    //lineStr="\n";
     copyToOutput(yyscanner,lineStr.view());
 
     fs->fileName      = absFileName;

[albert-github]

Very difficult problem.

My first thought was use \\ilinebr instead of \n but a that moment the example that I have for #10858:
example.tar.gz doesn't give good results anymore.

Second thought was remove just the insertCommentStart(yyscanner); around the line 1733 as shown above, but this leads to problems in the Fortran example: example.tar.gz

So probably a bit a more sophisticated approach is needed that the insertCommentStart(yyscanner); should not be added only under certain preconditions.

[doxygen]

@albert-github I've now moved back to my original fix for #10858, while addressing the issues you noticed at the time. It is a tricky thing to get right, so it could use some more testing.