Code documentation

[Boudewijn Rempt]

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:

http://www.koffice.org/developer/apidocs/krita/html/
http://www.englishbreakfastnetwork.org/apidocs/apidox-koffice/krita-apidocs/

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. 

http://www.englishbreakfastnetwork.org/apidocs/apidox-koffice/krita.log

> 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 :-)

Boudewijn