Kerberos documentation relay

[Sam Hartman]

Hi.

First, I agree that API documentation should have been solved yesterday
and starting as soon as possible is an incredibly good idea.

I tdefinitely think people should be encouraged to document APIs they
use and required to document APIs they add or significantly change.

I also think it would be great if you are able to find people who want
to spend time documenting Kerberos just to improve the documentation.
If you find them, we should do what it takes to enable their work.


I continue to believe that function level documentation should belong in
the header file or code, not in some website or database.  If you want
to generate a website or database that's great.  However, Perl, Python,
Java, Kerberos for Mac,Linux's ALSA, and many other projects demonstrate
that in-code documentation works reasonably well.

There may be other approaches that also work.

I don't believe any of the past efforts have failed because the
documentation was in-code--they have failed from an attempt to handle
things all at once.

If you collect a bunch of volunteers who are qualified to write
API-level documentation but who cannot write Doxygen comments, Javadoc
or the like, I agree it would be reasonable to have some way that these
people can contribute documentation.  However, I don't think it makes
sense to focus on these logistics until you get doc writers who could
not use whatever documentation system we adopt.

With the proposed committee, etc, I assume you are trying to provide a
mechanism for external contributors to get docs in.  In particular, I
assume you are not trying to raise the bar for existing people with
commit access to document their work.  If so, that seems like a great
idea.