commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Fredrik Westermarck <fredrik.westerma...@mdh.se>
Subject Javdoc formatting (Was: [lang] [patch] Javadoc improvements)
Date Tue, 19 Nov 2002 22:35:28 GMT
Henri Yandell wrote:
> I'm all for having consistent javadoc. Feel like writing up the 'rules'
> for the javadoc style you've ended up on? 

Hi!

Here is the promised rules that I try to follow when writing javadoc.

Ofcourse the Sun javadoc guidelines is used, this is only to be seen as 
an extension of them to make it easier for users reading the generated 
docs and developers with javadoc-popup capabilities from within their IDE.

General:
References to other objects, interfaces or methods use the @link-tag the 
first time it is referenced in a class or interface. On the following 
references always enclose it inside <code></code>.

Classes/Interfaces/Methods:
Use a short description of what the class/interface/metod is used for, 
enclose with <p></p>.

A longer description about what the class/interface/metod is used for 
and if it is needed how it is done. If it is nessesary include 
description of the parameters, what they are used for and how. Enclose 
with <p></p> where it is needed, try to divide into smaller parts (not 
to small!) to enhance readability of the generated Javadoc.

If an example is needed enclose it with <p><pre></pre></p>.
If an example was given write an explanation of the example within <p></p>.


--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message