Proposal on improvement to deprecated

Jonathan M Davis jmdavisProg at gmx.com
Sun Oct 2 13:16:10 PDT 2011


On Sunday, October 02, 2011 07:06:36 Michel Fortin wrote:
> On 2011-10-02 05:24:36 +0000, Jonathan M Davis <jmdavisProg at gmx.com> said:
> > deprecated("message", soft) void func1() {}
> > deprecated("message", hard) void func2() {}
> 
> This soft/hard thing is a little obscure, no one will understand what
> it means by looking a it. Why not have separated 'deprecated' and
> 'unavailable' states?

And make a new keyword? Or do something like

deprecated("message");
deprecated("message", unavailable);

I'm not exactly married to the idea of using the terms soft and hard. If you 
have a clearer way of saying the same thing, that's fine with me.

> Also, the message part should be part of the Deprecated ddoc section in
> the documentation. Since the compiler knows about ddoc, wouldn't it be
> better if it could just write out the Deprecated ddoc section in the
> error message? This way they can't become out of sync.

Well, that would be nice in the same way that it would be nice if the examples 
were taken from a unittest block and put into the documentation. ddoc could be 
improved at a leter date to automatically include the message that deprecated 
is given. Not to mention, there's not currently any "deprecated" section in 
any ddoc in Phobos that I'm aware of. The ones that I've been doing have a 
note at the beginning of the documentation which is quite similar to what 
would go in the deprecation message, but it's not its own section with a 
"Deprecated:" header. We could certainly do that, but we haven't been.

> > The way that Phobos will then deal with depreaction is as follows:
> > 
> > 1. A symbol which is going to be removed will be scheduled for
> > deprecation. This means that its documentation will mark it as
> > scheduled for deprecation, and it will be noted in the changelog that
> > it has been scheduled for deprecation. But there will be _no_ compiler
> > messages of any kind about the change. So, it's up to the programmer to
> > pay attention and notice if anything has been scheduled for
> > deprecation.
> 
> I'm not against that. But I think many people (including Walter) want
> to be notified by the compiler before it becomes an error. Passing
> straight from 'look at documentation' to 'compilation error' is too big
> of a step.

The problem is that a number of people have been complaining about the pragma 
messages. They don't _want_ messages. So, it's very hard to please everyone 
here. My proposal makes it possible to choose as to whether you want messages 
or not via the choice of -di vs -d in an attempt to placate both sides of that 
debate.

> - - -
> 
> In all this, my opinion is that 'deprecated' should be changed to emit
> informational messages (not errors) by default. Then you have this:
> 
> 1. scheduled for deprecation: documentation only
> 2. deprecated: informational message
> 3. unavailable: compilation error

Well, in my proposal, that's what would happen when compiling with -di. We 
_could_ make it so that that's what always happens and make it so that -d 
turns off the informational messages. That's not necessarily a bad idea and is 
simpler, which is a good thing.

> The scheduled for deprecation step would be mostly for things we know
> will be deprecated but that have no suitable replacement at the moment.

Well, that's not how Walter has wanted it used nor how we've been using it. 
But the main reason for Walter wanting to have essentially _everything_ that's 
deprecated to be "scheduled for deprecation" first is to avoid breaking 
anyone's code without warning if they don't compile with -d, and your 
suggestion would make it so that that doesn't happen, since deprecating 
something doesn't immediately break code.

So, your proposal has the downside of being a larger change with regards to 
the default behavior, but it's simpler and gives essentially the same benefits. 
Not to mention, it doesn't involve adding a new compiler flag, so it's probably 
simpler to implement too.

- Jonathan M Davis


More information about the Digitalmars-d mailing list