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