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