Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8141234

javac/javadoc should warn if @Deprecated annotation is present but @deprecated javadoc tag is missing

    Details

    • Type: Bug
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: tbd_minor
    • Component/s: tools
    • Labels:
      None

      Description

      There are two ways of expressing deprecation on a program element: putting the @deprecated tag into a javadoc comment, and annotation the program element using the @Deprecated annotation.

      When run with -Xlint:dep-ann, javac will issue a warning if the @deprecated javadoc tag is present but if the @Deprecated annotation is missing. However, no warning is issued if the opposite is true.

      A discussion among several of us (Buckley, Darcy, Gibbons, Marks) resulted in agreement that warnings should be issued for both cases. Specifically, there should be a warning emitted if the @Deprecation annotation is present but if the @deprecated javadoc tag is missing.

      This seems to fit nicely within the scope of -Xdoclint:missing. Thus the end result should be:

      -Xlint:dep-ann -- issues a warning if javadoc tag is present but annotation is missing (this works today)

      -Xdoclint:missing -- issues a warning if annotation is present but javadoc tag is missing (this needs to be added)

        Issue Links

          Activity

          Hide
          jjg Jonathan Gibbons added a comment -
          The warning should come from the doclint subsystem, which is available from both the javac and javadoc command lines.
          Show
          jjg Jonathan Gibbons added a comment - The warning should come from the doclint subsystem, which is available from both the javac and javadoc command lines.

            People

            • Assignee:
              ksrini Kumar Srinivasan
              Reporter:
              smarks Stuart Marks
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated: