Kerberos documentation relay
hartmans at MIT.EDU
Fri Aug 27 10:04:39 EDT 2010
>>>>> "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.
More information about the krbdev