Proposal
Add a @deprecatedReturn[A]
annotation allowing you to specify a less specific return type for a method using the annotation’s type parameter. The type of the type parameter MUST be a super-type of the method’s current return type.
For example:
class User {
@deprecatedReturn[Seq[Session]]
def activeSessions: List[Session]
}
In the example, treating the return value from the activeSessions
method as a List[A]
would be deprecated, but treating it as a Seq[A]
would not. If not typed explicitly, the compiler should prefer to type the return as Seq[A]
if possible1.
Motivation
Sometimes, return types for methods in the standard library (or other libraries) are accidentally made unnecessarily specific2, significantly restricting and constraining the ability of maintainers to improve or optimise implementations and fix bugs3.
Creating a deprecation cycle for an unnecessarily specific return type is not actually possible for public methods, as you still want the method to retain its current, sensible name. If you want to deprecate the method, you need to do each of the following steps, while waiting for a new, binary-incompatible version between each:
- create a second method with a different name and the less specific return type, and deprecate the old method
- remove the old method
- create a third method with the name of the original method and the signature of the second method, and deprecate the second method
- remove the second method
I opine that the above steps are ugly, painful, and generally infeasible. Alternatively, you could just change the return type of the method in the next binary-incompatible version and hope that it doesn’t silently break anyone’s code. A @deprecatedReturn
annotation would allow a simple migration to the less specific return type with warnings at any pace desired.
1. I’m not actually sure how this would work at the compiler level, though I do believe that the compiler currently prefers not to call deprecated methods when possible.
2. I don’t mean in any way to criticise contributors or maintainers who accidentally make return types overly specific; it’s easy to make such mistakes, and also easy for it to be the correct decision when written, but incorrect after some other changes.