doxygen
Invalid LaTeX caused by unclosed markdown codeblocks. No warnings provided
Describe the bug Doxygen produces LaTeX code which fails to compile with the error message:
...
Runaway argument?
{\end {DoxyCode} \doxylink {classExample}{Example} ex; ex.\+function\ETC.
! File ended while scanning use of \DoxyCodeLine.
<inserted text>
\par
...
A warning or error message by doxygen would be great to save users from digging through the LaTeX code to find the faulty doxygen comments.
This is triggered when having two functions both with unclosed markdown codeblocks like this:
/// @brief An example class
class Example {
public:
/**
* @brief An example Function
* ```
* Example ex;
* ex.run();
*/
void run() {}
/**
* @brief another function
* ```
* Example ex;
* ex.function();
*/
void function() {}
};
To Reproduce
For this example the invalid LaTex can be found in latex/classExample.tex and looks something like this:
\begin{DoxyCode}{0}
\DoxyCodeLine{\ \ \ Example\ ex;}
\DoxyCodeLine{\ \ \ ex.run();}
\DoxyCodeLine{\ */}
\DoxyCodeLine{\textcolor{keywordtype}{void}\ run()\ \{\}}
\DoxyCodeLine{\end{DoxyCode}
\doxylink{classExample}{Example} ex; ex.\+function();
The last \DoxyCodeLine is unclosed here.
Doxygen config: using the default provided config from my installation.
Expected behavior A warning or error message would be sufficient. However, since the input is faulty, this might not be considered a bug, but more of an inconvenience.
Version Doxygen Version: 1.13.2 OS: Fedora Linux 42 (Workstation Edition) I am using the Doxygen version that is provided by fedora.
A warning or error message by doxygen would be great to save users from digging through the LaTeX code to find the faulty doxygen comments.
This is triggered when having two functions both with unclosed markdown codeblocks
The problem here is that in verbatim blocks (line ``` but also <pre> ,f$, ...) doxygen allows also to have comment signs like */ so doxygen can, unfortunately, not decide what is part of a verbatim block inside a comment and what is the end of a comment. Doxygen considers everything after a start of a verbatim block till the corresponding end as part of the block.
So it is in my opinion not possible to solve this problem. (@doxygen do you see a possible solution?)
Oh, I see. But then I would expect DoxyCode block in the LaTeX code to also include
/**
* @brief another function
Looking at the generated latex it stops on /** instead of ```. I don't know anything about the internals of doxygen but maybe looking for the pattern ``` ... /** might be an option since it stops there already?
In the worst case, could the latex generator look at its own output and be like: "Oh I've opened an \DoxyCodeLine{ and before closing it I generated \end{DoxyCode}. Clearly there must be something wrong here?"
I agree it is a bit strange that there is no /** and @brief another function.
In the worst case, could the latex generator look at its own output and be like: "Oh I've opened an
\DoxyCodeLine{and before closing it I generated\end{DoxyCode}. Clearly there must be something wrong here?"
Not really possible as well as one doesn't know what is allowed everywhere in the LaTeX code, so doxygen and also the LaTeX converter cannot do anything about it.
@ben-hansske With the referenced commit a warning is added when encountering an unmatched C closing comment inside a verbatim section, as well as some logic changes that should prevent generating invalid output. Please verify if this fixes the problem for you. Do not close the issue, this will be done automatically when the next official release becomes available.
@doxygen I assume you saw the errors when building the doxygen documentation ...
The mentioned commit fixes the problem on my codebase. It both issues a warning but also manages to generate valid Latex code. Thank you very much!
This issue was previously marked 'fixed but not released', which means it should be fixed in doxygen version 1.15.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).