Re: [Doxygen-develop] Lint for Doxygen

[Dimitri v. H. <di...@st...>]

On Fri, Jul 26, 2002 at 04:31:40PM +0100, Simon Goodwin wrote:
> 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.

I recognise the problem of errors in the documentation blocks not being
detected and resulting in broken output. In fact I'm currently completely 
rewriting the way documentation is handled! I've started to write a 
recursive decent parser for documentation blocks (which builds an abstract 
syntax tree, instead of just doing only some lexical scanning as is done now).
This is quite a huge effort and it will take some time before it will appear
in doxygen's base line, however what I have now looks quite promissing already
(this is actually my third attempt, the other two were less successful ;-).

> 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.

These would not be detected by the new documentation parser, but could
be detected in an earlier pass.

> commands with / instead of \ at the start.
> 
> Unmatched or mismatched HTML brackets. 
> 
> &entity without following semicolon.
> 
> \ followed by an illegal character (probably should be \\)
> 

These are all be catchable by the new parser.

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

Doxygen does produce a warning when it ignores documentation blocks already.

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

Yes, please report common errors you see.

Regards,
  Dimitri