commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andreou Andreas <andy...@di.uoa.gr>
Subject Re: [math] @throws IllegalArgumentException
Date Tue, 17 Jun 2003 18:08:15 GMT
Phil Steitz wrote:

>--- "Craig R. McClanahan" <craigmcc@apache.org> wrote:
>  
>
>>On Sat, 14 Jun 2003, David Graham wrote:
>>
>>    
>>
>>>Date: Sat, 14 Jun 2003 17:02:35 -0600
>>>From: David Graham <dgraham1980@hotmail.com>
>>>Reply-To: Jakarta Commons Developers List <commons-dev@jakarta.apache.org>
>>>To: commons-dev@jakarta.apache.org
>>>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: commons-dev-unsubscribe@jakarta.apache.org
>>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>>
>>    
>>
>
>
>__________________________________
>Do you Yahoo!?
>SBC Yahoo! DSL - Now only $29.95 per month!
>http://sbc.yahoo.com
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
>  
>



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message