Hey, On Fri, Nov 5, 2010 at 9:35 AM, Gilles Sadowski <gil...@harfang.homelinux.org> wrote: >> > > > /** >> > > >- * Compute the value for the function. >> > > >- * @param x the point for which the function value should be >> > computed >> > > >- * @return the value >> > > >- * @throws FunctionEvaluationException if the function >> > > >evaluation fails >> > > >+ * Compute the value of the function. >> > > >+ * >> > > >+ * @param x Point at which the function value should be >> > computed. >> > > >+ * @return the value. >> > > > */ >> > > >- double value(double x) throws FunctionEvaluationException; >> > > >- >> > > >+ double value(double x); >> > > >} >> > > > >> > > >> > > IMHO we still need the @throws line in the javadoc. Otherwise end >> > > users are going to get a nasty surprise when they get an unchecked >> > > exception thrown. >> > > >> > >> > Any existing user code (throwing a "FunctionEvaluationException" at >> > some >> > point and catching it at another) will still work the same as before >> > (provided they change the "import" statement). No surprise to be >> > expected. >> >> So go ahead with the change, removing the throws from the declaration but >> keeping the javadoc as suggested previously. > > Again, what is it that you try to convey by specifying a single exception in > the Javadoc? Any unchecked exception can be thrown from a class that > implement the interface. > If the user code doesn't care that the evaluation fails, it should catch > everything and continue. Alternatively, if it cannot continue, it should let > the exception propagate. In either case, there isn't any useful information > from a Javadoc "@throws" tag: We already know that unchecked exceptions can > arise.
I don't know if it's relevant here, but it's standard practice in lots of code I've seen to document unchecked exceptions in the @throws block if your code explicitly throws it. However I would not put this tag on the interface method declaration, because maybe some implementation doesn't throw that exception. I would @inheritdocs on the implementor and specify the @throws there. > > Best, > Gilles Just my $0.02, James --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
