<html>
  <head>
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <br>
    <br>
    <div class="moz-cite-prefix">On 07/27/2018 04:34 PM, Alex Buckley
      wrote:<br>
    </div>
    <blockquote cite="mid:5B5BAC06.4000203@oracle.com" type="cite">On
      7/27/2018 4:12 PM, Jonathan Gibbons wrote:
      <br>
      <blockquote type="cite">Lots of @Deprecated annotations without
        corresponding @deprecated
        <br>
        javadoc tag. Should the @apiNote really be @deprecated. I also
        think
        <br>
        that using @Deprecated like this is "a bit smelly", and had a
        <br>
        discussion with Stuart "Dr Deprecator" regarding my concerns. If
        <br>
        nothing else, assuming the feature is a success, we are setting
        up a
        <br>
        precedent of marking an API as deprecated-for-removal, and then
        in
        <br>
        the next release, simply removing the annotation.
        <br>
      </blockquote>
      <br>
      JEP 12 is prepared to do exactly that for a Java SE API introduced
      in close connection with a preview feature -- see
      <a class="moz-txt-link-freetext" href="http://openjdk.java.net/jeps/12#Relationship-to-Java-SE-APIs">http://openjdk.java.net/jeps/12#Relationship-to-Java-SE-APIs</a>.
      <br>
      <br>
      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.
      <br>
      <br>
      Alex
      <br>
    </blockquote>
    <br>
    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".<br>
    <br>
    If we stay with the prescribed practice, the review comment about
    not having @deprecated text still stands.<br>
    <br>
    From JEP 12:<br>
    <br>
    <blockquote type="cite">When a Java compiler gives a <a
href="https://docs.oracle.com/javase/specs/jls/se9/html/jls-9.html#jls-9.6.4.6">removal
        warning</a> 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.)
    </blockquote>
    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.<br>
    <br>
    -- Jon<br>
  </body>
</html>