Re: source documentation tool doxygen

On Monday 16 January 2006 10:51, Tom Lane wrote:
> Neil Conway <neilc(at)samurai(dot)com> writes:
> > I don't think it would be all that painful. There would be no need to
> > convert the entire source tree to use proper Doxygen-style comments in
> > one fell swoop: individual files and modules can be converted whenever
> > anyone gets the inclination to do so. I don't think the maintenance
> > burden would be very substantial, either.
>
> In the previous go-round on this topic, I seem to recall some concern
> about side-effects, to wit reducing the readability of the comments for
> ordinary non-doxygen code browsing. I'd be quite against taking any
> noticeable hit in that direction.
>
> A quick look through the doxygen manual doesn't make it sound too
> invasive, but I am worried about how well it will coexist with pgindent.
> It seems both tools think they can dictate the meaning of the characters
> immediately after /* of a comment block.
>

In my experimentation, I found that there are really three paths for using
Doxygen on code.

(1) Do nothing to the code. Doxygen in this state works pretty well. You can
browse the code and you can find references to things. Some of the comments
are picked up correctly as-is. It does a really good job of formatting the
code for HTML.

(2) Do minimally invasive changes to make Doxygen recognize comments better.
Example: Move comments from behind to in-front, or vice-versa. Put an extra
'*' after '/*' to denote special documentation. This makes Doxygen especially
useful, because most things already have proper documentation and bringing
that out to the person who browses Doxygen's output is very good. All of a
sudden, we have a manual that reads like a book describing how PostgreSQL is
put together PLUS we still have the marked-up code.

(3) Do maximally invasive changes to the comments. This includes things like
using Doxygen-specific markup, putting in LaTeX for formulas, and putting in
cross-references. This is a huge amount of work (initial + maintenance) and
doesn't add much benefit beyond what (2) has. It makes the book read more
like a book, but it was already pretty readable.

It's not a question of WHETHER to use Doxygen. You can use it whether or not
anyone else wants to. It's really a question of how far do we bend backwards
to accomodate Doxygen. I'd say we just stick to moving comments around and
putting in the extra '*'s. Let's not encourage people to put in Doxygen
markup that isn't obvious. If someone contributes code with Doxygen mark-up,
we won't turn them down but we won't promise we'll keep their markup as
pretty as it was when they submitted it.

--
Jonathan Gardner
jgardner(at)jonathangardner(dot)net