Re: Thoughts on doxygen for Devel Docs/API?

["Kurt D. Zeilenga" <Kurt@OpenLDAP.org>]

At 12:48 PM 12/5/2006, Gavin Henry wrote:
>Hi All,
>
>What are your thoughts on using:
>
>http://www.stack.nl/~dimitri/doxygen/
>http://www.stack.nl/~dimitri/doxygen/docblocks.html
>
>I know a lot of OSS project use it, but not had any experience myself.

I cannot comment specifically on doxygen, but I can comment in
general.

The main problem in getting API documents, I think, is not
specific to whether such a tool is used or not.  Though
use of these tools can help in the initial work of documenting
an API (and might produce value even in the absence of
documentation blocks), there main benefit comes in maintaining the API
documentation.  That is, with or without the tool, we still
are faced with the problem that we have a huge pile of
undocumented code and documenting it won't be an easy task.

I think we need to be careful of taking on too many
documentation tasks at once.  Personally, I rather our
documentation energy put into the Admin Guide and Manual
Pages first...  but, hey, I'm not one to say "no" to those
willing and able to document OpenLDAP Software...

-- Kurt