Bug ID: JDK-8141234 javac/javadoc should warn if @Deprecated annotation is present but @deprecated javadoc tag is missing

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

Other
tbd_minorUnresolved

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)