[16170] in Kerberos_V5_Development
Re: Kerberos documentation relay
daemon@ATHENA.MIT.EDU (Sam Hartman)
Fri Aug 27 10:05:06 2010
From: Sam Hartman <hartmans@mit.edu>
To: Ken Raeburn <raeburn@mit.edu>
Date: Fri, 27 Aug 2010 10:04:39 -0400
In-Reply-To: <8902DBE7-2F89-4C8B-9020-E5F0487654FB@mit.edu> (Ken Raeburn's
message of "Fri, 27 Aug 2010 03:48:40 -0400")
Message-ID: <tsloccop2x4.fsf@mit.edu>
MIME-Version: 1.0
Cc: "krbdev@mit.edu Dev List" <krbdev@mit.edu>
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Errors-To: krbdev-bounces@mit.edu
>>>>> "Ken" == Ken Raeburn <raeburn@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.
_______________________________________________
krbdev mailing list krbdev@mit.edu
https://mailman.mit.edu/mailman/listinfo/krbdev
