Package: doxygen Version: 1.8.8-5 Severity: serious Justification: Creates broken documentation in many packages
Hi, So doxygen 1.8 added support for interpreting markdown, and it does this in all normal comment blocks before applying the normal doxygen formatting. Unfortunately, they also chose to enable this by default, so any package that is building docs against this version, which didn't update the doxyconf configuration using this version, to see that this option exists and to turn it off if it breaks the generated documentation, is going to run a fairly high chance of generating fairly horribly broken docs. A quick canary for the extent of this problem is to search for: 'warning: unexpected command endcode' Which went by uncommented on (or I assume inspected) in logs such as was posted to https://bugs.debian.org/680896 and many other places. This is just one fairly common way this fails horribly, resulting in all the comments *above* a @code section being treated as code, and the code section itself being dumped literally to the output - but there are quite a few other ways this will generate awful unreadable documentation when markdown syntax is inadvertently applied to an existing codebase. Unless we want to ship with a lot of fairly useless -doc packages, it seems like this should probably be disabled by default, until people have become more aware of the problem and have taken steps to avoid it in their own source. I found a lot of build logs that show people having this problem, but no discussion of the cause, the impact, or the fix. I suspect a lot of people who build -doc packages rarely or never actually read them themselves ... Fixing the ones that are already broken is probably going to be something of a major operation in its own right, but the mood in #d-d seemed to be that we should start by limiting the damage here and then tackle that part separately. Ron -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected]
