Canonical ordering of javadoc comments

[Roedy Green]

Are you aware of any accepted conventions on the precise ordering of
Javadoc comments?

What do you use yourself?
--
Roedy Green Canadian Mind Products
http://mindprod.com

"Species evolve exactly as if they were adapting as best they could to a changing world, and not at all as if they were moving toward a set goal."
~ George Gaylord Simpson

 

[Lew]

Are you aware of any accepted conventions on the precise ordering of
Javadoc comments?

What do you use yourself?

A doc comment is composed of a main description followed by a tag section ....
First sentence - The first sentence of each doc comment should be a summary
sentence, containing a concise but complete description of the declared
entity.

A doc comment ... is made up of two parts --
a description followed by block tags.

Normally method comments have the block tags in the order @param tags,
@return, @throws, @version, @see, @since, @deprecated.
<http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#orderoftags>

It's safest to follow Sun's conventions, which have been well established
since about 2000, judging by the copyright date.

 

[Roedy Green]

Normally method comments have the block tags in the order @param tags,
@return, @throws, @version, @see, @since, @deprecated.
<http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#orderoftags>

This turned out to be a bit more complicated than that paragraph at
Sun would suggest.

I have posted an essay on my findings at
http://mindprod.com/jgloss/javadoc.html

I have also converted by body of source to the official standard with
a little program I wrote. Source for the converter is posted at.

https://wush.net/websvn/mindprod/fi...th=/com/mindprod/repair/TidyLeadComments.java

You would have to tweak it to find the patterns in on your own code,
and precise details of your new desired format.

I have not yet committed the complete body of converted code. I am
doing a few other things to try to stop pointless deltas.



--
Roedy Green Canadian Mind Products
http://mindprod.com

"Species evolve exactly as if they were adapting as best they could to a changing world, and not at all as if they were moving toward a set goal."
~ George Gaylord Simpson