Re: [math] @throws IllegalArgumentException

[Andreou Andreas]

Phil Steitz wrote:

--- "Craig R. McClanahan" <[EMAIL PROTECTED]> wrote:
 

On Sat, 14 Jun 2003, David Graham wrote:

   

Date: Sat, 14 Jun 2003 17:02:35 -0600
From: David Graham <[EMAIL PROTECTED]>
Reply-To: Jakarta Commons Developers List <[EMAIL PROTECTED]>
To: [EMAIL PROTECTED]
Subject: Re: [math] @throws IllegalArgumentException
     

I am dutifully cleaning up the CheckStyle warnings in my code and I am
hesitating to remove @throws IllegalArgumentException, which CheckStyle
currently complains about. I am a little ambivalent about this.  There is
       

a
   

property (checkstyle.javadoc.checkUnusedThrows) that we can set to make it
ignore these. I notice that [lang] has this set to false. I actually
       

prefer
   

to leave these "unused throws tags" in. Any strong opinions on this?
       

There are many Java classes that use the @throws tag with a
RuntimeException.  Removing it from the javadoc is a very bad idea because
it always helps to know what exceptions a method throws.  I'm assuming
checkstyle is complaining because the exception isn't listed in the actual
throws signature which is easily fixable.
     

My personal opinion is that it's entirely reasonable to Javadoc-document
RuntimeException exceptions that might be thrown, even if they are not
included in the "throws" clause on the method itself.  The entire reason
for making the actual exception a RuntimeException is so that an
application calling the method casually will not have to worry about
try/catch blocks -- but advanced users will DEFINITELY appreciate the
hints about what kinds of checks the method is actually performing.
   

I agree. In general, we are calling out the boundary/exception generating
conditions in the body of the javadoc comments; but I would like to add the
tags as well.  The only way I can make checkstyle happy when doing this is to
add the throws clauses as David suggests.
 

Isn't there a checkstyle property exactly for this reason?
Quoting from their docs:
"JavadocMethod
allowUndeclaredRTE -> whether to allow documented exceptions that are 
not declared if
they are a subclass of java.lang.RuntimeException"
This defaults to false.

 

Therefore, it also seems reasonable to me that CheckStyle should support a
mode where it still complains about Javadoc'd exceptions no listed in the
"throws"  clause -- but ONLY if those exceptions are not
RuntimeExceptions.
   

I agree. 

 

FWIW, the JavaServer Faces spec (for which I'm co-spec-lead) is trying to
be pretty rigorous about documenting where some typical runtime exceptions
might be thrown -- particularly things like NullPointerException on null
arguments that should really be non-null -- with the goal of improving the
predicatability of various implementations of JavaServer Faces.  I'd be
*really* unhappy with CheckStyle if it complained about all of the
explicit JavaDoc declarations (which it sounds like it will right now).
   

David

     

Craig

---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
   



__________________________________
Do you Yahoo!?
SBC Yahoo! DSL - Now only $29.95 per month!
http://sbc.yahoo.com
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
 



---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]