[jboss-dev] Developer javadoc is essential!

[Flavia Rainone]

AFAIK, we don't have guidelines for writing Javadocs (please, correct me 
if I'm wrong).
So, I thought it could be useful to post this link on JBoss dev list:
http://java.sun.com/j2se/javadoc/writingdoccomments/
IMO, this document provides very useful guidelines and I have used it as 
a reference for years now.

Kabir Khan escreveu:
> I am currently working on a "first pass" on the javadocs for the mc 
> dependency and kernel projects. As I get more familiar with the 
> internals of mc, I will keep adding to this.
> On 2 Jun 2009, at 11:42, Thomas Diesler wrote:
>
>> Jason,
>>
>> yes, I very much agree.
>>
>> This has been brought under way for MC = please monitor
>>
>> https://jira.jboss.org/jira/browse/JBMICROCONT-442
>>
>> To enforce "must have javadoc" I created
>> https://jira.jboss.org/jira/browse/JBAS-6994
>>
>> Perhaps you like to ping the individual leads to create/name their 
>> respective JIRA issues that are supposed to improve the situation in 
>> their camp and have those linked to the one above.
>>
>> cheers
>> -thomas
>>
>> Jason T. Greene wrote:
>>> Hi Guys,
>>> The javadoc/code comments in our core modules are VERY lacking, so 
>>> it is incredibly difficult for new folks to understand how anything 
>>> is supposed to work (I have been hearing some groaning about this 
>>> recently).
>>> All of our code, especially SPI or API classes must have javadoc 
>>> which explains in detail the following things:
>>> 1) How the module is supposed to be used (and how it is actually 
>>> used if known)
>>> 2) The intended behavior, and any aspect of it that is known to be 
>>> broken or a hack (so that someone can differentiate between a design 
>>> problem and just an unimplemented section that needs to be fixed)
>>> 3) Crticial preconditions (e.g. "this class expects that the same 
>>> vfs handle instance be reused during a redeploy")
>>> 4) Thread-access design (e.g. "this class is thread-safe and can be 
>>> accessed from multiple threads", "this class is not thread-safe, and 
>>> all callers must use a shared lock to access", "this class is 
>>> intended to have an instance-per-thread")
>>> If we can't answer these simple questions, then it is likely our 
>>> design is flawed.
>>
>> --xxxxxxxxxxxxxxxxxxxxxxxxxxxx
>> Thomas Diesler
>> JBoss, a division of Red Hat
>>
>> 2009 Red Hat Summit and JBoss World.
>> Chicago. September 1-4, 2009.
>> http://www.redhat.com/summit
>> http://www.jbossworld.com
>> xxxxxxxxxxxxxxxxxxxxxxxxxxxx
>> _______________________________________________
>> jboss-development mailing list
>> jboss-development at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/jboss-development
>
> _______________________________________________
> jboss-development mailing list
> jboss-development at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-development

-- 
Flavia Rainone | JBoss Core Developer 

M: (+55) (+11) 8122-5466
YIM/MSNIM: flaviarnn