|
28 | 28 |
|
29 | 29 | /** |
30 | 30 | * Indicates that the annotated element and the code transitively {@linkplain |
31 | | - * javax.lang.model.element.Element#getEnclosedElements() enclosed} within it are <b>null-marked |
32 | | - * code</b>: there, type usages are generally considered to exclude {@code null} as a value unless |
33 | | - * specified otherwise. Using this annotation avoids the need to write {@link NonNull @NonNull} many |
34 | | - * times throughout your code. |
| 31 | + * javax.lang.model.element.Element#getEnclosedElements() enclosed} within it are in <b>null-marked |
| 32 | + * context</b>: there, type usages are generally considered to exclude {@code null} as a value |
| 33 | + * unless specified otherwise. Using this annotation avoids the need to write {@link |
| 34 | + * NonNull @NonNull} many times throughout your code. |
35 | 35 | * |
36 | | - * <p>For a comprehensive introduction to JSpecify, please see <a |
37 | | - * href="https://jspecify.dev">jspecify.org</a>. |
| 36 | + * <p>Conversely, {@link NullUnmarked} puts its enclosed code in null-unmarked context, the same as |
| 37 | + * unannotated code. These annotations work as an inclusion-exclusion pair: of the annotations of |
| 38 | + * <i>either</i> type on all enclosing elements (methods, classes, etc.), only the <i>nearest</i> |
| 39 | + * (most narrowly enclosing) one is in effect. |
| 40 | + * |
| 41 | + * <p>For important information common to all four nullness annotations, see {@link |
| 42 | + * org.jspecify.annotations}. To learn more about JSpecify, see <a |
| 43 | + * href="https://jspecify.dev">jspecify.dev</a>. |
38 | 44 | * |
39 | 45 | * <h2 id="effects">Effects of being null-marked</h2> |
40 | 46 | * |
41 | | - * <p>Within null-marked code, as a <i>general</i> rule, a type usage is considered non-null (to |
42 | | - * exclude {@code null} as a value) unless explicitly annotated as {@link Nullable}. However, there |
43 | | - * are several special cases to address. |
| 47 | + * <p>In null-marked context, a type usage is generally considered to be non-null unless explicitly |
| 48 | + * annotated with {@link Nullable @Nullable}. However, there are a few special cases to address. |
44 | 49 | * |
45 | 50 | * <h3 id="effects-special-cases">Special cases</h3> |
46 | 51 | * |
47 | | - * <p>Within null-marked code: |
| 52 | + * <p>Within null-marked context: |
48 | 53 | * |
49 | 54 | * <ul> |
50 | | - * <li>We might expect the type represented by a <b>wildcard</b> (like the {@code ?} in {@code |
51 | | - * List<?>}) to be non-null, but it isn't necessarily. It's non-null only if it {@code |
52 | | - * extends} a non-null type (like in {@code List<? extends String>}), or if the <i>class</i> |
53 | | - * in use accepts only non-null type arguments (such as if {@code List} were declared as |
54 | | - * {@code class List<E extends String>}). But if {@code List} does accept nullable type |
55 | | - * arguments, then the wildcards seen in {@code List<?>} and {@code List<? super String>} must |
56 | | - * include {@code null}, because they have no "upper bound". (<a |
| 55 | + * <li>A <b>wildcard</b> (as seen in {@code List<?>}) generally represents a nullable type, unless |
| 56 | + * either it or its corresponding type parameter has a non-null upper bound. (<a |
| 57 | + * href="https://bit.ly/3ppb8ZC">Why?</a>) |
| 58 | + * <li>A <b>type parameter</b> itself is a different case. It is never really "unbounded"; if no |
| 59 | + * upper bound is given explicitly, then {@code Object} is filled in by the compiler. This |
| 60 | + * means the example {@code class MyList<E>} is interpreted identically to {@code class |
| 61 | + * MyList<E extends Object>}, making the upper bound <i>non-null</i> {@code Object}. (<a |
57 | 62 | * href="https://bit.ly/3ppb8ZC">Why?</a>) |
58 | | - * <ul> |
59 | | - * <li>Conversely, a <b>type parameter</b> is always considered to have an upper bound; when |
60 | | - * none is given explicitly, {@code Object} is filled in by the compiler. The example |
61 | | - * {@code class MyList<E>} is interpreted identically to {@code class MyList<E extends |
62 | | - * Object>}: in both cases the type argument in {@code MyList<@Nullable Foo>} is |
63 | | - * out-of-bounds, so the list elements are always non-null. (<a |
64 | | - * href="https://bit.ly/3ppb8ZC">Why?</a>) |
65 | | - * </ul> |
66 | | - * <li>Otherwise, being null-marked has no consequence for any type usage where {@code @Nullable} |
67 | | - * and {@code @NonNull} are {@linkplain Nullable##applicability <b>not applicable</b>}, such |
68 | | - * as the root type of a local variable declaration. |
69 | | - * <li>When a type variable has a nullable upper bound, such as the {@code E} in {@code class |
70 | | - * Foo<E extends @Nullable Bar>}), an unannotated usage of this type variable is not |
71 | | - * considered nullable, non-null, or even of "unspecified" nullness. Rather it has |
72 | | - * <b>parametric nullness</b>. In order to support both nullable and non-null type arguments |
73 | | - * safely, the {@code E} type itself must be handled <i>strictly</i>: as if nullable when |
74 | | - * "read from", but as if non-null when "written to". (Contrast with {@code class Foo<E |
75 | | - * extends Bar>}, where usages of {@code E} are simply non-null, just like usages of {@code |
76 | | - * String} are.) |
77 | | - * <li>By using {@link NullUnmarked}, an element within null-marked code can be excluded and made |
78 | | - * null-unmarked, exactly as if there were no enclosing {@code @NullMarked} element at all. |
| 63 | + * <li>When a type parameter has a nullable upper bound, such as the {@code E} in {@code class |
| 64 | + * Foo<E extends @Nullable Bar>}, an unannotated usage of the associated <b>type variable</b> |
| 65 | + * (within that class) must be handled conservatively: it is nullable when read, yet cannot |
| 66 | + * have {@code null} assigned to it. |
| 67 | + * <li>Any type usage where {@code @Nullable} and {@code @NonNull} are {@linkplain |
| 68 | + * Nullable##applicability <b>not applicable</b>}, such as the root type in a local variable |
| 69 | + * declaration, is unaffected by being in null-marked context. |
79 | 70 | * </ul> |
80 | 71 | * |
81 | 72 | * <h2 id="where">Where it can be used</h2> |
82 | 73 | * |
83 | 74 | * {@code @NullMarked} and {@link NullUnmarked @NullUnmarked} can be used on any package, class, |
84 | 75 | * method, or constructor declaration; {@code @NullMarked} can be used on a module declaration as |
85 | | - * well. ({@link NullUnmarked @NullUnmarked} is not supported on modules, since it's already the |
86 | | - * default.) Special considerations: |
| 76 | + * well. ({@code @NullUnmarked} is not supported on modules, since it's already the default.) |
| 77 | + * Special considerations: |
87 | 78 | * |
88 | 79 | * <ul> |
89 | | - * <li>To apply this annotation to an entire (single) <b>package</b>, create a <a |
| 80 | + * <li>To apply these annotations to an entire (single) <b>package</b>, create a <a |
90 | 81 | * href="https://docs.oracle.com/javase/specs/jls/se26/html/jls-7.html#jls-7.4.1">{@code |
91 | | - * package-info.java}</a> file there. This is recommended so that newly-created classes will |
92 | | - * be null-marked by default. This annotation has no effect on "subpackages". <b>Warning</b>: |
93 | | - * if the package does not belong to a module, be very careful: it can easily happen that |
94 | | - * different versions of the package-info file are seen and used in different circumstances, |
95 | | - * causing the same classes to be interpreted inconsistently. For example, a package-info file |
96 | | - * from a {@code test} source path might hide the corresponding one from the {@code main} |
97 | | - * source path, or generated code might be compiled without seeing a package-info file at all. |
98 | | - * <li>Although Java permits it to be applied to a <b>record component</b> declaration (as in |
99 | | - * {@code record Foo(@NullMarked String bar) {...}}), this annotation has no meaning when used |
100 | | - * in that way. |
101 | | - * <li>Applying this annotation to an instance <b>method</b> of a <i>generic</i> class is |
102 | | - * acceptable, but is not recommended because it can lead to some confusing situations. |
103 | | - * <li>An advantage of Java <b>modules</b> is that you can make a lot of code null-marked with |
104 | | - * just a single annotation (before the {@code module} keyword). <b>Warning</b>: Even if you |
105 | | - * annotate the module for a library as {@code @NullMarked}, this has no effect for users who |
106 | | - * place the library on the class path; it affects only those who place the library on the <a |
107 | | - * href="https://openjdk.org/projects/jigsaw/quick-start">module path</a>, which is less |
108 | | - * commonly used. |
| 82 | + * package-info.java}</a> file and annotate the package declaration there. This annotation has |
| 83 | + * no effect on "subpackages". <b>Warning</b>: if the package does not belong to a module, be |
| 84 | + * very careful: it can easily happen that different versions of the package-info file are |
| 85 | + * seen and used in different circumstances, causing the same classes to be interpreted |
| 86 | + * inconsistently. |
| 87 | + * <li>An advantage of Java <b>modules</b> is that you can put a lot of code in null-marked |
| 88 | + * context with just a single annotation (before the {@code module} keyword). <b>Warning</b>: |
| 89 | + * Even if you annotate the module for a library as {@code @NullMarked}, this has no effect |
| 90 | + * for users who place the library on the class path; it affects only those who place the |
| 91 | + * library on the <a href="https://openjdk.org/projects/jigsaw/quick-start">module path</a>, |
| 92 | + * which is less commonly used. |
| 93 | + * <li>Applying this annotation to an <b>annotation interface</b> does <i>not</i> express that |
| 94 | + * annotations of that type are synonymous with {@code @NullMarked}. It has the same meaning |
| 95 | + * as it does anywhere else. |
109 | 96 | * <li>If both {@code @NullMarked} and {@code @NullUnmarked} appear together on the same element, |
110 | 97 | * <i>neither</i> one is recognized. |
111 | 98 | * </ul> |
|
0 commit comments