--- "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.
> 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]
