[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
Re: Thoughts on doxygen for Devel Docs/API?
<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.
--
Kind Regards,
Gavin Henry.
Managing Director.
T +44 (0) 1224 279484
M +44 (0) 7930 323266
F +44 (0) 1224 824887
E ghenry@suretecsystems.com
Open Source. Open Solutions(tm).
http://www.suretecsystems.com/