[jboss-dev] Documenting the MC codebase

[Thomas Diesler]

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"

http://mockito.googlecode.com/svn/tags/latest/javadoc/org/mockito/Mockito.html 


Providing documentation in that way is easy for the consumer because it 
can always up to date and available online. For the provider of the docs 
it's also easy because docs can be changed in the same place were code 
changes happen.

As you might guess, improving the docs of the MC code base is important 
and dear to me because it represents a significant non-trivial portion 
of our infrastructure. New comers can only make qualified changes 
effectively when the docs are good.

views?

cheers
-thomas

-- 
xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Thomas Diesler
JBoss OSGi Lead
JBoss, a division of Red Hat
xxxxxxxxxxxxxxxxxxxxxxxxxxxx