GnuCash developper documentation

[Benoit Grégoire]

Today is my rant day ;)

Here are some comments and suggestions about developer documentation in 
GnuCash.  As a fairly new (8 months) GnuCash hacker, I think I have an good 
perspective on this.  Perhaps some of the following isn't true.  If so, the 
mere fact that I haven't noticed by now is proof enough that it is far from 
obvious.  Currently, the barrier to entry for GnuCash is very high, even if 
new developers are greeted with patience and open arms.  The problems 
include:

1-Gnucash is simply huge.  Here are some useless but interesting statistics 
about the size of the codebase (Physical source line of code, excluding 
comments and whitespace):
ansic:       207 585 (78.57%)
scheme:         32 731 (12.39%)
2-The gnucash design info pages, which are the primary developper 
documentation, are no longer kept up to date.
3-Module documentation is incomplete.  How to create a new module, insert it 
in the build system and get gnucash to load it not documented.
4-Several important scheme functions are completely undocumented.  (Are ANY 
scheme functions documented?)  
5-There needs to be a FAQ on how to add new GUI elements:  preference pages, 
menu entry, etc.
6-The GnuCash codebase is very scarcely commented.

Solutions:

1-Not much we can do about this.  There is some code duplication, but you can 
only go so far.  Flagging unimplemented or non-functional header files or 
functions would be a good thing however.
2-I don't think we have the human ressources to keep this updated in it's 
current form, now that no one is payed to work on GnuCash.  One solution 
would be to move this documentation into the source or header files and use a 
tool like doxygen (http://www.stack.nl/~dimitri/doxygen/) to generate the 
doc.  It would certainly help with keeping the documentation updated.  But we 
need a tool that will work with Scheme.
3-Update the module documentation.  And at least create "dummy" modules (one 
in scheme, one in C) to serve as code example.  Perhaps that would be 
documentation enough. 
4-Since scheme doesn't have header files, we need a solution like 2
5-We need to write it and keep it updated, especially since the APIs for this 
moved a lot recently.
6-I presume that this comes from a time when Gnucash was developed intensively 
by a tight group of people, relying on complete and up to date design 
documents.  I know some people consider that the code should speak for itself 
and comments are a distraction.  But someone coming into a new project can't 
be expected to know every function name, and to such a person, ANY code is 
hard to understand without general comments about what a section of code or a 
non trivial function call is expected to do.   Obviously we can't go back an 
comment the entire codebase, but I think this should be remembered by all 
hackers for new or modified code.

Obviously all this is a huge amount of work, but would help attract casual 
hackers that will then become addicted...  Agreeing on what should be done 
would be a good start.  I think 2 and 3 should be the priority.

Comments?

-- 
Benoit Grégoire
http://step.polymtl.ca/~bock/