commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Stephen Colebourne" <>
Subject Re: Javdoc formatting (Was: [lang] [patch] Javadoc improvements)
Date Thu, 21 Nov 2002 21:06:34 GMT
My personal style is to put the <p> between the paragraphs on the blank
line. It has an advantage that it is less in the way when reading the
comment in the source code. Similarly, I don't include the </p> as its
redundent in HTML (OK, I know we should incude it, but it works fine without

Also, is <p><pre> </pre></p> the correct HTML syntax. I thought that
was at the same 'level' as <p> and so shouldn't be embedded. Could be wrong


From: "Fredrik Westermarck" <>
> 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
> --
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message