wood burning stoves 2.0*
The moose likes Java in General and the fly likes declare runtime exceptions in javadoc? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Java » Java in General
Bookmark "declare runtime exceptions in javadoc?" Watch "declare runtime exceptions in javadoc?" New topic
Author

declare runtime exceptions in javadoc?

Mr. C Lamont Gilbert
Ranch Hand

Joined: Oct 05, 2001
Posts: 1170

When writing my javadoc for my api, should I put runtime exceptions in there or not? For instance, in the text of the method I say the object must have been started before this method is called. Is it enouogh to make this statement, or should I go ahead and add a @throws IllegalStateException if object is not started, type of thing!?
Akshay Kiran
Ranch Hand

Joined: Aug 18, 2005
Posts: 220
look into the api, there are lots of places where the method detail has a section called Throws which declares the exceptions that the method might throw, not necessarily at compiletime, and they have also mentioned it in the explanation of the method, for example, this method from the Integer class. I think the best example to emulate would be the API docs, isn't it?



[ October 16, 2005: Message edited by: Akshay Kiran ]
[ October 16, 2005: Message edited by: Akshay Kiran ]

"It's not enough that we do our best; sometimes we have to do<br />what's required."<br /> <br />-- Sir Winston Churchill
Layne Lund
Ranch Hand

Joined: Dec 06, 2001
Posts: 3061
I think it is common practice to document runtime exception with the @throws tags. However, you don't necessarily need to declare them in the throws clause of the method's header.

Layne


Java API Documentation
The Java Tutorial
Adam Richards
Ranch Hand

Joined: Nov 03, 2005
Posts: 135
I vote yes, document all the exceptions you throw. Callers can decide whether they want to catch them, assuming they know how to something intelligent with them.
Tony Morris
Ranch Hand

Joined: Sep 24, 2003
Posts: 1608
It is mandatory as per Design By Contract, which you are using, inadvertantly ad hoc or not. Would you like me to write a contract that surprises you with undocumented behaviour?

You might instead prefer a throws annotation that either refers to a specification of when the exception is thrown, or states it in English.
For example:



The key point is that you document your contract. English is a substandard specification language, but usually (but not always) better than nothing.


Tony Morris
Java Q&A (FAQ, Trivia)
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: declare runtime exceptions in javadoc?
 
Similar Threads
Handling checked and unchecked Exceptions?
Throw and System.out.println ?
Interface Exception Signature - aka leaky abstractions
Exception Handling
logging runtime exceptions