Summary

Allow SuppressWarnings annotation to be used in in all declaration contexts, including package declarations.

Problem

While allowed to be used on type and module declarations, among other targets, SuppressWarnings annotations cannot be used on package declarations and several other declaration contexts.

Solution

Remove the @Target meta-annotation from SuppressWarnings to implicitly allow it in all declaration contexts.

Note: while the SuppressWarnings annotation does have a JLS section (9.6.4.5. @SuppressWarnings), the section doesn't mention the target list therefore doesn't appear to need to be updated.

Specification

@@ -27,24 +27,54 @@

 import java.lang.annotation.*;
 import static java.lang.annotation.ElementType.*;

 /**
- * Indicates that the named compiler warnings should be suppressed in the
- * annotated element (and in all program elements contained in the annotated
- * element).  Note that the set of warnings suppressed in a given element is
- * a superset of the warnings suppressed in all containing elements.  For
+ * Indicates the warnings to be suppressed at compile time in the
+ * annotated element, and in all elements contained in the annotated element.
+ *
+ * <p>The {@code SuppressWarnings} annotation interface is applicable
+ * in all declaration contexts, so an {@code @SuppressWarnings}
+ * annotation can be used on any element.
+ * As a matter of style, programmers should always use this annotation
+ * on the most deeply nested element where it is effective. For example, if you want to
+ * suppress a warning in a particular method, you should annotate that
+ * method rather than its class.
+ *
+ * <p>The set of warnings suppressed in a given element is
+ * a union of the warnings suppressed in all containing elements.  For
  * example, if you annotate a class to suppress one warning and annotate a
- * method to suppress another, both warnings will be suppressed in the method.
+ * method in the class to suppress another, both warnings will be suppressed in the method.
  * However, note that if a warning is suppressed in a {@code
  * module-info} file, the suppression applies to elements within the
  * file and <em>not</em> to types contained within the module.
+ * Likewise, if a warning is suppressed in a {@code
+ * package-info} file, the suppression applies to elements within the
+ * file and <em>not</em> to types contained within the package.
  *
- * <p>As a matter of style, programmers should always use this annotation
- * on the most deeply nested element where it is effective.  If you want to
- * suppress a warning in a particular method, you should annotate that
- * method rather than its class.
+ * <p>Java compilers must recognize all the kinds of warnings defined in
+ * the <cite>Java Language Specification</cite> (JLS section {@jls
+ * 9.6.4.5}) which include:
+ *
+ * <ul>
+ * <li> Unchecked warnings, specified by the string {@code "unchecked"}.
+ * <li> Deprecation warnings, specified by the string {@code "deprecation"}.
+ * <li> Removal warnings, specified by the string {@code "removal"}.
+ * <li> Preview warnings, specified by the string {@code "preview"}.
+ * </ul>
+ *
+ * Whether or not a Java compiler recognizes other strings
+ * is a quality of implementation concern.
+ * Compiler vendors should document the
+ * additional warning names they support.
+ * Vendors are encouraged to cooperate to ensure
+ * that the same names work across multiple compilers.
+ *
+ * @implNote
+ * In addition to the mandated suppression strings, the {@code javac}
+ * reference implementation recognizes compilation-related warning
+ * names documented in its {@code --help-lint} output.
  *
  * @author Josh Bloch
  * @since 1.5
  * @jls 4.8 Raw Types
  * @jls 4.12.2 Variables of Reference Type
@@ -50,11 +80,11 @@
  * @jls 4.12.2 Variables of Reference Type
  * @jls 5.1.9 Unchecked Conversion
  * @jls 5.5 Casting Contexts
  * @jls 9.6.4.5 @SuppressWarnings
  */
-@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, MODULE})
+// Implicitly target all declaration contexts by omitting a @Target annotation
 @Retention(RetentionPolicy.SOURCE)
 public @interface SuppressWarnings {
     /**
      * The set of warnings that are to be suppressed by the compiler in the
      * annotated element.  Duplicate names are permitted.  The second and
@@ -61,16 +91,10 @@
      * successive occurrences of a name are ignored.  The presence of
      * unrecognized warning names is <i>not</i> an error: Compilers must
      * ignore any warning names they do not recognize.  They are, however,
      * free to emit a warning if an annotation contains an unrecognized
      * warning name.
-     *
-     * <p> The string {@code "unchecked"} is used to suppress
-     * unchecked warnings. Compiler vendors should document the
-     * additional warning names they support in conjunction with this
-     * annotation type. They are encouraged to cooperate to ensure
-     * that the same names work across multiple compilers.
      * @return the set of warnings to be suppressed
      */
     String[] value();
 }