commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From James Ring <...@jdns.org>
Subject Re: svn commit: r1030464 [1/3] - in /commons/proper/math/trunk/src: main/java/org/apache/commons/math/ main/java/org/apache/commons/math/analysis/ main/java/org/apache/commons/math/analysis/integration/ main/java/org/apache/commons/math/analysis/inte
Date Thu, 04 Nov 2010 23:13:56 GMT
Hey,

On Fri, Nov 5, 2010 at 9:35 AM, Gilles Sadowski
<gilles@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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message