(ann) @Deprecated annotation has no effect on packages

The documentation of the @Deprecated annotation says:
"A program element annotated @Deprecated is one that programmers are discouraged from using, typically because it is dangerous, or because a better alternative exists. Compilers warn when a deprecated program element is used or overridden in non-deprecated code."

Packages are program elements (as implicitly defined by the ElementType enum) and the @Deprecated annotation does not have a @Target meta-annotation that prevents it from being applied to packages. So the second quoted sentence above says the compiler will warn if you use a package that is deprecated. This is done by adding a @Deprecated annotation to the package declaration in a package-info.java in the package directory. But it does not in fact have any effect.

The meaning of "using" a package is clear. Referencing any class within a package is a use of the package, just as referencing any field or method in a class is a use of the class and will draw a warning if the class is deprecated.

Either the compiler should issue warnings when a deprecated package is referenced, or the quoted text should be modified.