Forums Register Login

"@since" or "@throws" tag of Javadoc

+Pie Number of slices to send: Send
I am not clear about "@since" and "@throws" tag .
First "@since" tag:
Below is a sample doc comment for a class.
/**
* Description of class
*
* @author xyz
* @version 1.0
* @since 1.0
*/
Is this(above) right doc comment(only concerned tags are given) for "@since" tag ?
If this class is modified, and as a result version becomes "1.2", then doc
comment modifies to --
/**
* Description of class
*
* @author xyz
* @version 1.2
* @since 1.0
*/
Am i right ( "version" changed to "1.2" and "since" is as it is "1.0")?

Suppose a new class is addedd in version 1.3 -- Is it ok to write doc comment for
this class like this(written below):
/**
* Description of class
*
* @author xyz
* @version 1.3
* @since 1.3
*/
For "@throws" tag:
Sun Java doc guidelines : "Multiple @throws tags (also known as @exception) should be listed alphabetically by the exception names."
Does this apply in method declaration also, to be specific
which is more appropriate from POV order of exception :
methodA() throws IOException, RemoteException; // Exceptions ordered alphabetically
or
methodA() throws RemoteException,IOExption ; // Exceptions are not ordered alphabetically .
Or it does not matter here at all.
Regards,
Akash
+Pie Number of slices to send: Send
 

Originally posted by Akash Singh:
...
For "@throws" tag:
Sun Java doc guidelines : "Multiple @throws tags (also known as @exception) should be listed alphabetically by the exception names."
...



Hi Akash--
It's my understanding that the notes on javadoc ordering of tagged exceptions is suggested as a documentation convention only; I do not believe the javadoc will be produced incorrectly if you do not put your exceptions in alphabetical order. Furthermore, the ordering of declared exceptions in your method signatures is irrelevant; your code should compile either way.
I wish i could comment on the @since tag, but i've never used it so I won't lead you astray.

Regards,
Paul
+Pie Number of slices to send: Send
Regarding @since, I believe the answer to all Akash's questions is "yes". All the comments shown are correct.
+Pie Number of slices to send: Send
Hi Jim, Paul:
Thank you very much.
Regards,
Akash
Thank you my well lotioned goddess! Here, have my favorite tiny ad!
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com


reply
reply
This thread has been viewed 672 times.
Similar Threads
Tag files in jar...how??
Javadoc and coding conventions
the value of <%@taglib uri="" %>?
Exception
static inner class
More...

All times above are in ranch (not your local) time.
The current ranch time is
Mar 28, 2024 16:45:33.