[Doxygen-develop] Lint for Doxygen

[Simon G. <sim...@at...>]

Hello Doxygenators,

Having documented quite a lot of things with Doxygen now I find that I and others
consistently make mistakes that are not reported by the document parser. Before
I encourage all the other programmers at ATD to use Doxygen - and I have to sort
out all their mistakes - I want to extend our documentation toolchain to spot and
report as many errors as possible. At the moment it takes several passes of running
Doxygen, examining the log, editing the headers, and round again to get everything
documented - and even then there tend to be hidden mark-up errors that only surface
when the document gets read by a human.

I am aware that this is not easy and not something that can be 100% comprehensive.
There is also a risk that spurious errors may be reported, and so I would like to make this
checking optional, at least at first, despite the creeping featuritus evident from the long
list of Doxygen options already. ;-)

My experience of compiler-writing is that writing a compiler for correct source is
easy compared with writing one that gives good diagnostics when incorrect
source is supplied - perhaps because of the free-form source, C compilers don't
seem to try to do this very hard - which is a pity as more incorrect programs are
submitted for compilation than correct ones (or your makefile is broken). But even
if we can't catch every error of imaginative programmers, it would be both friendly and
convenient for all concerned to put some effort into reporting common errors.

The first thing I want to do is ask if others reckon this would be a useful extension
to Doxygen, however it might be implemented.

Then I'd like to know what errors are worth checking for. After that we can try to categorise
the errors and work out if it is worth checking for them inside Doxygen, in a separate program
(hence the Lint reference) or by mixing the trick.

I welcome suggestions about implementing this. I favour the idea of extending Doxygen itself
or using Gnu tools to minimise the need for new code, but if there's anything already around
that does such a job, I'd like to hear of it.

But the first thing to do is to list the problems that I've often seen and which seem worth sifting
out.


Things to check for in a Lint for Doxygen
=========================

// ! or //* ! instead of //! and /*! (etc.) 

//<! instead of //!< and equivalents.

commands with / instead of \ at the start.

Unmatched or mismatched HTML brackets. 

&entity without following semicolon.

\ followed by an illegal character (probably should be \\)

More than two documentation blocks before an entity (only the last two are
parsed, earlier ones are ignored).

---------------------------------

I'm sure there are others. Comments welcome. :-)

Simon Goodwin, Technology Programmer, Attention to Detail Ltd.

-- 
Simon Goodwin <sim...@at...