commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
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:54:20 GMT
On 4 November 2010 22:35, 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.

Seems to me we should document any Exceptions that our code throws,
along with the reasons for them.
That way, the user can create specific catch clauses.

Also, the other RuntimeExceptions are generally unpredictable, whereas
in this case, these Exceptions are only
generated under specific circumstances.

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

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


Mime
View raw message