Re: [MO-java-dev] Java Doc

[Ted H. <hu...@ap...>]

Vincent Massol wrote:

>- overall architecture first (this is the overview.html and package.html
>javadoc for example - if we're staying javadoc land)
>- how the objects are linked together (that's the top level class
>comments)
>
>I agree that method level comments are useful only sporadically,
>

+1

For the next iteration of Struts, we'd like to base most of the 
documentation in  the "Developer Guides"  we've been publishing as 
package descriptions

http://jakarta.apache.org/struts/api/org/apache/struts/taglib/bean/package-summary.html#package_description

This way everything travels together and it's easier to keep it all in 
synch.

I'll look for an opportunity to starting putting something together for 
this project, but I like to do this sort of thing as I go and let it 
grow in the telling.

-Ted.