commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: svn commit: r1042610 - /commons/proper/math/branches/MATH_2_X/src/main/java/org/apache/commons/math/linear/RealVector.java
Date Tue, 07 Dec 2010 13:59:22 GMT




On Dec 7, 2010, at 7:19 AM, sebb <sebbaz@gmail.com> wrote:

> On 7 December 2010 09:18, Gilles Sadowski <gilles@harfang.homelinux.org> wrote:
>> Hi.
>> 
>>> On 6 December 2010 22:21, Gilles Sadowski <gilles@harfang.homelinux.org>
wrote:
>>>>>>>> -     * @deprecated in 2.2 (to be removed in 3.0). Please
use
>>>>>>>> -     * {@link #map(UnivariateRealFunction)} directly with
>>>>>>>> -     * the function classes in package
>>>>>>>> -     * {@link org.apache.commons.math.analysis.function}.
>>>>>>>> +     * @deprecated in 2.2 (to be removed in 3.0).
>>>>>>> 
>>>>>>> Why not leave the reference to #map(UnivariateRealFunction) ?
>>>>>> 
>>>>>> Because the package "function" does not exist in MATH_2_X.
>>>>> 
>>>>> I know that, but #map(UnivariateRealFunction) does exist (in the same
>>>>> source file).
>>>>> 
>>>>> It was only the reference to the package name that was wrong.
>>>>> 
>>>>> If the replacement for the deprecated methods is not
>>>>> #map(UnivariateRealFunction), then whatever is the replacement should
>>>>> be specified in the Javadoc.
>>>> 
>>>> The replacement is the method "map" (which exists) together with the
>>>> appropriate function (which doesn't, unless someone wants to backport the
>>>> "function" package).
>>> 
>>> There are several implementations of UnivariateRealFunction, e.g.
>>> PolynomialFunctionLagrangeForm.
>>> 
>>> Are these not suitable as parameters to the map method?
>> 
>> They are, but they do not provide a replacement for the deprecated methods,
>> which is the point of a more detailed deprecation message.
>> 
>>>> I think that we agreed with Phil that when the replacement doesn't exist,
it
>>>> is sufficient to warn the users with a terse deprecation message.
>>> 
>>> I don't think it is right to leave the user totally in the dark as to
>>> how to resolve the deprecation warnings.
>> 
>> There is no possible resolution in 2.2. The deprecation warning says: "You
>> will have to modify that code when upgrading to 3.0".
> 
> In which case the upgrade path should be mentioned elsewhere in the
> release documentation.
> 
> But if we already know what the methods are in 3.0, why not add a note
> to the class Javadoc to give the user the information they need?
> 
I am now regretting having opened this can of worms.  The 3.0 API is evolving and we are trying
to do as good a job as we can including deprecations in 2.2 for things we know are going to
be removed in 3.0. Beyond "terse" deprecations, I don't think it's reasonable to try to maintain
documentation on the still-evolving 3.0 API in the 2.x branch.

Phil


>> 
>> Regards,
>> 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
> 

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


Mime
View raw message