[Aegisvm-devel] Documentation

[Philip F. <pw...@cs...>]

Hi all,

Pete brought up the issue of documentation a while ago, and Chris is
bringing it up again.  The fact is that the code base is not very
well documented, which makes it hard for new contributors to become
productive quickly.  It has become quite a pressing issue now, and
I would like to get some input from you guys.

I guess my take is that I do not want to maintain a separate set
of documentation on top of the code base.  The reasons being
the code is a rapidly moving target, and it is difficult to
avoid the doc from going out of sync with the code.  I think
economy and low barrier of entry are both important for a 
young project like ours.  My preference is to have a very simple
document discribing in very high level terms the overall structure
of the code base, and then leave all the detail documentation
in the source file. 

Have you guys heard of this very wonderful project called 
doxygen (http://www.stack.nl/~dimitri/doxygen/)?  It translates
embedded javadoc style documentation in C/C++ source file into hyperlinked
HTML docs.  If we use it then we could maintain only the source files,
but we still have external documentations that are much easier to
navigate.

What do you guys think?  Would such set up solve the problem?  Is 
doxygen the kind of tool that you would be happy to work with?
Is it still an overkill, and you would prefer something even more
lightweight?  Let me know.

Philip

*  Philip W. L. Fong
*  School of Computing Science
*  Simon Fraser University, Burnaby, B.C., Canada V5A 1S6
*  pw...@cs...  
*  http://www.cs.sfu.ca/~pwfong/
*  (604)719-2333