Kerberos documentation relay

[Sam Hartman]

>>>>> "Ken" == Ken Raeburn <raeburn at MIT.EDU> writes:

    Ken> A couple of starts were made towards using doxygen in the header files in the past, which failed for reasons other than the choice of doxygen, I think.  Is there any reason to reverse direction now?

I strongly support this direction.  I understand there was a push on
krbcore to use doxygen comments in source files *not* in headers.
Unfortunately doxygen will then organize the documentation by source
file, and it is very easy to forget to mark every internal function as
@internal, and the resulting doc quality is significantly less.

The best Doxygen output comes from docs in your public headers with good
use of grouping and a few special doxygen files to link things together.
In some cases it may make sense to split out really long function
documentation into a special file.

My doxygen experience is not infinite, but I did play with it a fair bit
on an internal Painless Security project, and I looked a lot at G++'s
use of Doxygen, Doxygen's use of Doxygen and ALSA's use of Doxygen.