Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

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

 
Akash Singh
Ranch Hand
Posts: 80
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Paul Tongyoo
Ranch Hand
Posts: 91
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Regarding @since, I believe the answer to all Akash's questions is "yes". All the comments shown are correct.
 
Akash Singh
Ranch Hand
Posts: 80
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Jim, Paul:
Thank you very much.
Regards,
Akash
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic