RFR: JDK-8192963/JDK-8206986 JEP 325: Switch Expressions (Preview)

[Jonathan Gibbons]

On 07/27/2018 04:34 PM, Alex Buckley wrote:
> On 7/27/2018 4:12 PM, Jonathan Gibbons wrote:
>> Lots of @Deprecated annotations without corresponding @deprecated
>> javadoc tag. Should the @apiNote really be @deprecated. I also think
>> that using @Deprecated like this is "a bit smelly", and had a
>> discussion with Stuart "Dr Deprecator" regarding my concerns. If
>> nothing else, assuming the feature is a success, we are setting up a
>> precedent of marking an API as deprecated-for-removal, and then in
>> the next release, simply removing the annotation.
>
> JEP 12 is prepared to do exactly that for a Java SE API introduced in 
> close connection with a preview feature -- see 
> http://openjdk.java.net/jeps/12#Relationship-to-Java-SE-APIs.
>
> However, com.sun.source.tree is a JDK-supported API, not a Java SE 
> API, so JEP 12 is silent on whether new methods in BreakTree.java and 
> CaseTree.java should be flagged as if on the same level as a java.* 
> API in the "Reflective" bucket. You could argue that a client of 
> com.sun.source.tree is informed enough that they don't hand-holding 
> about preview features.
>
> Alex

The anti-pattern this is setting up is at the use-site of the "preview" 
API.  Either you have to do @SuppressWarnings("removal") at a high 
level, and risk suppressing more warnings than you intended, or you do 
it at a fine grain level, which clutters the code. Either way, you set 
up the risk of forgetting to remove the annotations should the feature 
transition from "preview" to "standard".

If we stay with the prescribed practice, the review comment about not 
having @deprecated text still stands.

 From JEP 12:

> When a Java compiler gives a removal warning 
> <https://docs.oracle.com/javase/specs/jls/se9/html/jls-9.html#jls-9.6.4.6> 
> for a use of a terminally deprecated API connected with a preview 
> feature, it is recommended that the text of the warning be customized 
> to indicate the connection. (This is a quality of implementation 
> issue; the generation of a warning is mandated, as is the ability to 
> suppress it in source code, but the precise text is not.) 
The problem with this suggestion is that there is no easy way to 
mechanically determine the reason for the deprecation, except an ugly 
heuristic that says, "if it's deprecated for removal since the current 
release, it's probably related to a preview feature". Uugh.   It would 
be *slightly* better if the @apiNote was converted to @deprecated, 
because then we could make a general improvement to show the @deprecated 
text when any API that has been deprecated for removal is used.

-- Jon
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20180727/4db4bf26/attachment.html>