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)