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