At the moment this topic is wide open.
Doxygen seems to be the more popular tool (in particular among C-programmers)
and it puts more effort in to generate documentation. However on a code as
large as NWChem it suffers from segmentation faults.
Robodoc simply extracts documentation from the source code comments. Hence it
is more limited in its ability to extract information when the code hasn't been
commented. However, as an advantage I haven't seen it crash on NWChem yet.
The main reason for checking this stuff in a this point is that we ship it
with the development tar-balls and if something does not work we can tell
people how they can reproduce the problems we are hitting. Alternatively,
this allows developers to play with this stuff as well. However, anyone playing
with this must consider that we may choose another tool (or no tool at all)
as some point in the future. Hence putting a lot of work into the documentation
at this point is unwise.
