[spud] doxygen

[Olly Betts]

In message <20001031162945.B11417@mrs30.quns.cam.ac.uk>, Mark Shinwell writes:
>What do people think about using doxygen?  I believe the KDE people are
>about to switch to using it, so it must be fairly decent.

We use it at work.  Seems to do the job pretty well without getting in the
way.  I'm in favour of using it.

I've a couple of reservations - such systems can lead to swathes of
pointless documentation which just wastes people time when they try to read
it.  The sort of thing I mean is:

  class Widget
    - this class represents a widget

  string Widget::get_description(bool verbose)
    - get a description of a widget
    
    parameters:
      verbose - flag to produce more verbose output

People feel required to write something, but sometimes don't actually
provide any information which you couldn't have inferred from the class and
method names.  This example is extreme, but a lot of documentation from such
systems has this sort of flavour to it.

The other problem is that the code and documentation comments can drift
apart if people aren't careful to update both together.  You sometimes find
new parameters which aren't documented, or parameters documented which no
longer exist.  But people are more likely to fail to update documentation in
a separate file.

Both of these are largely avoidable if people are aware of them rather than
expecting doxygen or a similar system to be a magic bullet.

Cheers,
Olly