Kerberos documentation relay

[Greg Hudson]

On Fri, 2010-08-27 at 10:04 -0400, Sam Hartman wrote:
> 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.

This was my idea, the idea being that it would allow internal and API
functions to be documented in the same manner.  Based on Sam's findings,
I've abandoned this preference; we can return to the plan of documenting
APIs in header files.

New APIs which I've added (such as the krb5_tkt_creds APIs) already have
Doxygen comments, although I don't believe we currently have build rules
to run Doxygen yet.

> 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.

I don't think we need to worry about this yet, but yeah, some of the
more complicated functions may want page-long documentation.

That may be more tolerable in the API headers if we split krb5.h out
into more than one giant file (which I believe we have due to
no-longer-relevant restrictions in tools).