aegisvm-devel

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

RE: [Aegisvm-devel] Documentation

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

Hi

On Sun, 5 May 2002, Chris Neumann wrote:
> 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.

Good point.  You have spelled out the most important criteria for
picking an appropriate documentation tool.

I only spent like half an hour reading doxygen's manual.
It looks like it's pretty straightforward.  For one thing, it accepts
javadoc style documentation, which makes it possible to learn only one set
of mark up to work with both C and Java.  Secondly, I believe that
one doesn't need to know every detail of a technology to be productive.
I think, by just looking at how others write their documentation
markup, you should have everything you need to start documenting
your code.

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

I agree with you.

> 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?

This is perfect!
 
Now it becomes very clear that as the first consumers of the documentation
you guys know so much more about what is needed that I do.  I think
it is much better if you guys actually have some kind of access to the CVS
repository in order to actually have more influence on this whole
thing.  However, as a language security researcher I am a very 
paranoid person.  Do you know if there is any configuration thing I
could do with the CVS repository to make sure that we can control
the demage we would do to each other's work?  Pete, how do other
projects do this?  I looked through the sourceforge admin interface
but couldn't find anything useful...

Philip