The annotation @java.lang.Deprecated is defined with @Retention(SOURCE). This is confusing, since SOURCE means "Annotations are to be discarded by the compiler." But in fact the compiler does not discard @Deprecated annotations. They are in fact recorded in the generated class file, but using the "Deprecated" attribute, not an annotation. This distinction is subtle and likely to cause head-scratching. It would be better if either:
(a) @Deprecated were defined with @Retention(CLASS), meaning "Annotations are to be recorded in the class file by the compiler" (but in fact not recorded *as an annotation*, and the documentation could state this), or
(b) the documentation for @Deprecated were updated to say, e.g., "The @Retention of this annotation is SOURCE even though it does affect the compiled class file, because deprecation is not recorded as an annotation but as a special attribute in the class file."