archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8280744: Allow SuppressWarnings to be used in all declaration contexts

Browse source 
Reviewed-by: iris
This commit is contained in:
Joe Darcy 2022-01-28 00:44:13 +00:00
parent 40a2ce2033
commit 78574057a4
1 changed files with 44 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

63
src/java.base/share/classes/java/lang/SuppressWarnings.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2004, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2004, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -29,21 +29,52 @@ 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
* 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.
* 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.
* Indicates the warnings to be suppressed at compile time in the
* annotated element, and in all elements contained in the annotated
* element.
*
* <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
* <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 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>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
@ -52,7 +83,7 @@ import static java.lang.annotation.ElementType.*;
* @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 {
/**
@ -63,12 +94,6 @@ public @interface SuppressWarnings {
* 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();