Markdown: unordered list

[AndreasMatthias]

Doxygen seems to have an issue with markdown files that start with an unordered list.

This example.tar.gz produces the following warning:

.../example/Readme_1.md:2: warning: Invalid list item found

Note that only Readme_1.md, that starts with an unordered list, has an issue, while
Readme_2.md is rendered correctly.

Tested with doxygen 1.11.0 (3ce42bf)

[doxygen]

@AndreasMatthias Please verify if the referenced commit fixes the problem for you. Do not close the issue, this will be done automatically when the next official release becomes available.

[albert-github]

I found anothre problem:

/// \file

/// \copydoc fie()
void fie2();

/// \brief the second brief
/// - foo
/// - bar
/// - baz
void fie(){}

which doesn't give a warning and the result is:

Example: example.tar.gz

[doxygen]

@albert-github Slightly improved fix that should also address the issue you reported.

[albert-github]

Shouldn't spaces be added in commentscan.l as indicated in e65420e#r141879029 ?
As now when the part from \copydetails contains an initial space this space would be eaten as well (I don't have an example for it).

[doxygen]

@albert-github I tried this initially, but it resulted in other problems.

[AndreasMatthias]

Tested with 7323ef1.
It works as long as the markdown file is read directly. But the issue reappears if you include the markdown file with @include{doc}.

See this example: example.tar.gz

[albert-github]

@doxygen
When looking at the example and running with -d commentcnv I see:

/** @mainpage
 *   \ilinebr \ifile ".../example/Readme_1.md" \iline 1 \ilinebr    - foo
 * - bar
 * - baz
 *
 *  \ilinebr \ifile ".../example/foo.cpp" \iline 2  */
]

looks like the copyToOutput in combination with insertStartComment for this type of cases do not perform properly, maybe these functions have to be extended with a test on \ilinebr at the end of a line and handle it (more or less) as a \n (and also adjust lineNr with the \ifile).
Note maybe also the handling of the \t needs some adjustment.

[albert-github]

Regarding the problem noted in #10858 (comment) I've just pushed a proposed patch, pull request #10861

I also added a bit of an extended example to show results with snippets and to see whether or not warning line numbers are correct: example.tar.gz

[doxygen]

@albert-github I saw your pull request only after I already made a different fix ☹️. Not sure yet which fix is better. My fix doesn't need to add a newline and correct the line number, so maybe is a bit more generic... Let me know your thoughts.

[albert-github]

@doxygen
My thoughts about both patches

• my patch tackles the problem at the moment of the usage of \include{doc} / \snipper{doc} and therefore does not interfere with other usage of "space" usage. The adjustment of the line numbers is nowadays not a problem as we have the internal command \iline that is already used in this case.
• your patch is in a routine stripIndentation that even has 2 versions:
  1. util.h:QCString stripIndentation(const QCString &s);
  2. util.h:void stripIndentation(QCString &doc,const int indentationLevel);

where only the first version is adjusted i.e. the one used in scanner.l and the one in pyscanner.l is not corrected. Furthermore the fortranscanner.l is not considered at all.

Running a quick test with Fortran (see attached example) showed that my fix fixed the Fortran case as well and yours didn't ( I didn't test python, but similar problems expected).

I think best is to tackle the problem at the source of the problem.

Fortran example: example.tar.gz

[doxygen]

@albert-github Thanks for the feedback. I agree with your remarks. I've reverted my fix and merged yours.

[albert-github]

Code of #10861 has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[AndreasMatthias]

Thank you for fixing it so quickly.

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.11.0.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).