[phobos] Proposed changes to std.math + introduce std.mathspecial

[Andrei Alexandrescu]

On 11/17/10 3:30 PM, Michel Fortin wrote:
> Le 2010-11-17 à 17:47, Andrei Alexandrescu a écrit :
>
>> On 11/17/10 2:42 PM, Michel Fortin wrote:
>>> But won't that just become a convenient excuse to forget putting the deprecation notice in the documentation? It sounds redundant:
>>>
>>> /**
>>>   * Blah blah blah...
>>>   * Deprecated: use the homonym functions in std.mathspecial.
>>>   */
>>> deprecated("use the homonym functions in std.mathspecial")
>>> double lgamma(double);
>>
>> I thought it's pretty clear that having active deprecation notes is not redundant at all. The right solution to avoiding redundancy is to have ddoc insert the deprecation note in the generated text.
>
> Ok, so now you have two places where you can write your deprecation notes instead of one, but only one will make the compiler output a helpful error message?
>
> What if one day you want to deprecate functions informally (in the documentation only) and at a later time you want to deprecate them formally (making the compiler complain), should you coppy all your ddoc-style deprecated sections to a string following the deprecated keyword?
>
> Is there any advantage in using the deprecated("note") syntax instead of making the compiler use the existing Deprecated section of ddoc to print a helpful comment?

The advantage is that the deprecation error message will hint the user 
on what to do to fix things.

Andrei