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

[Jonathan M Davis]

On Wednesday, November 17, 2010 15:30:00 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?

It sounds to me like Michel wants the compiler to take the deprecation note from 
the ddoc comment and use it for both the documentation and the compiler's 
deprecation note whereas Andrei wants to put the deprecation note in the code 
and have ddoc take that and add it as a deprecation note in the ddoc when 
generating the ddoc. So, it's a question of which place you put the note. It 
ends up in both places either way.

- Jonathan M Davis