boud at valdyas.org
Wed Mar 8 15:34:36 CET 2006
On Wed, 8 Mar 2006, Leonardo Giordani wrote:
> I want to suggest everyone writing code to document it, especially to document
> functions. This is REALLY important not only for a new Krita hacker (like me)
> but always for long time developers.
We try to be good :-). There's generated apidox available at two places:
I'm not sure which one is more up-to-date.
> I do not know if KOffice or KDE is using some automatic documentation tool:
> I'm using doxygen for my work and it is really a big improvement and help for
> me and my co-workers.
Yes, that's what we're using. I see we've got 11 errors again -- probably
generated in the heat of the release coding.
> I will also suggest to give some constraints for hand-witten documentation
> (doc/ directory); nothing revolutionary, just a bit of order: all text files
> ending with ".txt" or all text files ending with nothing, author name and
> mail in each document, etc...
Well, the .doc directory is just a scratchpad of ideas and notes. Not really
something to depend on it. Not sure I want to standardize beyond adding a README
saying "Warning: here be dragons. Obsolete dragons."
> I know that documenting is boring, especially when you are not used to it: but
> I experienced that trying to explain to someone what you are doing is a good
> way to better understand it. Not to mention that after 2-3 months common
> people do forget why they wrote that piece of code in that manner.
True. But it's a counsel of perfection. We inherited a completely undocumented
codebase, and compared to that we've made huge progress :-)
More information about the kimageshop