[spud] doxygen

[Olly Betts]

In message <20001031170336.E11417@mrs30.quns.cam.ac.uk>, Mark Shinwell writes:
>On Tue, Oct 31, 2000 at 04:45:33PM +0000, Olly Betts wrote:
>> 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.
>
>True, perhaps accessor functions like this can be documented separately?
>I don't know if doxygen supports anything like this...

Perhaps my point wasn't clear (or perhaps yours isn't...)

What I'm saying is that if all you can think to tell me about
get_description() is that it "gets a description", then don't bother giving
it a documentation comment (doxygen lists classes and methods with no
documentation comments too).

Doxygen also warns you about undocumented methods/classes/etc, so no
documentation is also better than pointless documentation since there's a
nagging reminder to do something about it.

To illustrate, this is good:

  string Widget::get_description(bool verbose)
    - returns a human-readable description of the object intended to aid
      debugging

    parameters:
      verbose - if true, describe the entire state of the object.  Otherwise
                only the most important members are mentioned.

Whereas this is a waste of space:

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

Without documentation comments you'd get this:

  string Widget::get_description(bool verbose)

This conveys the same information in a much briefer form.  You probably need
to understand C++ syntax to read it, but if you don't, why are you reading
the source documentation anyhow?

Cheers,
Olly