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
<quote who="Kurt D. Zeilenga">
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...
Understood. But here's a thought, don't take new code submissions unless they follow whatever code documentation method we adopt?
That one's obviously for the future, but the sooner it starts, the sooner new developers can get their head round the code and the sooner you can take a back seat (like you say at http://www.openldap.org/project/kurt/) ;-)
My 2 pence....
Thanks,
Gavin.
-
Gavin Henry -
Kurt D. Zeilenga