RE: [Aegisvm-devel] Documentation

[Chris N. <cne...@sf...>]

I was just thinking how much I've gotten used to using JavaDoc... =)

I think that this would be an excellent (and easy to implement)
solution to our documentation worries.  Provided that the required
commenting conventions are not too crazy (I haven't had a chance to
review them yet), it should have a minimal learning curve, and thus,
significantly decrease the time required to understand the overall
code base.

Personally, I would still like to see some level of separate
documentation maintained in addition to the generated doxygen files.
Mainly, these would be the "big picture" items that give an overall
picture of the entire system (since it can be difficult to see how
everything fits together from dozens of separate interface files).
These might include:

- A high-level overview of the entire AegisVM system and its major
  modules.
- An appendix of naming conventions for functions and constants used
  within the implementation (e.g. all values prefixed with "J_OPC"
  represent XXX and are defined in file YYY)
- Some sort of basic, high-level architectural document to guide the
  progression of the design/implementation (perhaps it's worth seeing
  if doxygen can generate dependency diagrams...?)
- Others?

Ok...there's my two cents.  Enjoy the rest of your weekend!

- Chris

-----Original Message-----
From: aeg...@li...
[mailto:aeg...@li...]On Behalf Of Philip
Fong
Sent: Saturday, May 04, 2002 12:40 PM
To: aeg...@li...; jt...@sf...; na...@sk...
Subject: [Aegisvm-devel] Documentation


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


_______________________________________________________________

Have big pipes? SourceForge.net is looking for download mirrors. We supply
the hardware. You get the recognition. Email Us: ban...@so...
_______________________________________________
Aegisvm-devel mailing list
Aeg...@li...
https://lists.sourceforge.net/lists/listinfo/aegisvm-devel