[jboss-dev] Documenting the MC codebase

[David M. Lloyd]

On 03/01/2010 06:34 AM, Thomas Diesler wrote:
> There is an effort that started in May-2009 which is about providing
> better API docs for the MC code base
>
> https://jira.jboss.org/jira/browse/JBMICROCONT-442
>
> Recently, I came across an open source project that takes a radically
> different (read opposite) approach to API docs than we have with the MC
> code base.  Mockito says: "all docs are in javadoc"

I like this idea.  I do not like how they used a specific class for the 
"main" page though.  If I were doing it this way, I'd use the overview page 
and package summary pages a lot more thoroughly, and try to tie the 
hierarchy of the documentation to the structure of the Javadoc in some way.

For "chapters" which are not directly related to a package, I'd use a 
separate HTML page linked from the overview page.

Also, if you're doing this already, you might as well re-skin the Javadoc 
too :)

-- 
- DML ☍