On Dec 7, 2010, at 7:19 AM, sebb <seb...@gmail.com> wrote:
> On 7 December 2010 09:18, Gilles Sadowski <gil...@harfang.homelinux.org>
> wrote:
>> Hi.
>>
>>> On 6 December 2010 22:21, Gilles Sadowski <gil...@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-unsubscr...@commons.apache.org
>> For additional commands, e-mail: dev-h...@commons.apache.org
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
