Promote -deprecation to -Xlint:deprecation

[som-snytt]

Promote -deprecation to -Xlint:deprecation, and demote complaining about missing since to lint.

(Setting the lint option also enables ordinary -deprecation; the lint is a superset.)

Was: Adopt forRemoval flag for deprecated.

[diesalbla]

The class Symbol includes an instance-unique id value, of type Int. Instead of using a Set of symbols, could we use a set of their ids? Sets of integers have efficient implementations.

[som-snytt]

A sage conjecture.

[eed3si9n]

JEP 277: Enhanced Deprecation says

However, the @Deprecated annotation ended up being used for several different purposes. Very few deprecated APIs were actually removed, leading some people to believe that nothing would ever be removed. On the other hand, other people believed that everything that was deprecated might eventually be removed, which was never the intent either. (Although it wasn't stated explicitly in the specifications, various documents mentioned that deprecated APIs would be removed at some point.) This resulted in an unclear message being delivered to developers about the meaning of @Deprecated, and what, if anything, developers should do when they encountered usage of a deprecated API. Everybody was confused about what deprecation actually meant, and nobody took it seriously. This in turn has made it difficult ever to remove anything from the Java SE API.

How did Java programmers confuse themselves to the point that they don't know what @Deprecated mean? Does this confusion exist among the Scala programmers? At least for me, @deprecated means that the API is eventually going away. Adding forRemoval I feel like would actually increase the uncertainty rather than clarity.

If some API says @deprecated("Don't use it.", since="1.0") in Scala 2.13, what would that mean? I would much rather go the opposite direction of adding @restricted or whatever for non-removal warnings like #7790.

[som-snytt]

@eed3si9n Although I have some opinions about deprecation and migration which I won't bother to elaborate, I will offer unequivocally that deprecation is not just about removing API.

For example, "It encourages bad coding practices", https://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/deprecation.html, is a possible semantics.

You could deprecate appending to a List with no intention of removing the API.

Someone, maybe smarter, said Scala is different from Java because it throws out API all the time.

But even Scala would not throw out list append. There is no mechanism for doing so. But it could deprecate append when the receiver is statically known to be a List. The message might suggest ListBuffer, or prepend and reverse, or what have you.

Deprecation is a way to ward off impending doom. It is a prayer which says to the gods, But I am too unimportant to destroy just now, let me live a bit longer as you purge the evil-doers. It is always unclear how long such a dispensation may last.

Edit: I mean to describe deprecation as understood, not to suggest that Scala couldn't rewrite the rules, though in that case I'd probably suggest discarding the word "deprecation".

[som-snytt]

I just read Shakespeare's Tempest. @NthPortal is like Ariel, swooping in to confuse us by liking each contradictory opinion.

You know it was only an illusion that the ship split apart in the storm, which itself was also an illusion.

"Their rising senses begin to chase the ignorant fumes that mantle their clearer reason."

[NthPortal]

@som-snytt lol, I just thought both of you made good points.

Honestly though, I would prefer a different annotation for the List example you gave, because it's still part of the API, and if you need to append a single value to a List (which is conceivable), it's what you should use. In my mind, deprecated means "don't use this anymore", not "well this is generally not what you want, but sometimes it is, so you might not want to use it, unless you actually do".

[adriaanm]

I'm reminded of our notorious greek cliff-avoidance comment in the compiler. Sadly, it doesn't look like we'll get this ship/boat/better-deprecation-story to the 2.13 port.

[adriaanm]

As I said on the other PR -- I'd really-really-really like to get something like this into 2.14, since we can't get there for 2.13 it seems. Closing this one until we branch for 2.14 😞

[som-snytt]

Reopening to revert just the surprisingly controversial parameter.

Restored to RC1 because of the lint option.

[adriaanm]

Maybe we can sneak in forRemoval using hashtags. message="don't use it #forRemoval", or when less serious, message="don't use it #justKidding".

[som-snytt]

@NthPortal footnote, the constructors for java boxed primitives says: It is rarely appropriate to use this constructor. They tease us with "rarely", but it would be an example where "don't use this" is qualified.