Re: [jboss-dev] Documenting the MC codebase

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