Summary

Document in the JLS and libraries specification that a Deprecated annotation does not have an effect on packages.

Problem

An @Deprecated annotation can be applied to packages, but has no effect there. (Likewise, an @Deprecated annotation has no effect if applied to a local variable or parameter.)

Solution

Update the JLS to state the @Deprecate on a package is a no-op and make analogous changes in the javadoc for java.lang.Deprecated.

Specification

JLS 9.6.4.6

Change

"Use of the @Deprecated annotation on a local variable declaration or on a parameter declaration has no effect."

to

"Use of the @Deprecated annotation on a local variable declaration or on a parameter declaration or on a package declaration has no effect."

Analogous change in java.lang.Deprecated:

+ * <p> Use of the @Deprecated annotation on a local variable declaration or
+ * on a parameter declaration *or on a package declaration* has no effect.
+ *