Debian Codegraph @

src/main/java/org/jspecify/annotations/NullUnmarked.java

raw
1 /*
2 * Copyright 2022 The JSpecify Authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.jspecify.annotations;
17
18 import static java.lang.annotation.ElementType.CONSTRUCTOR;
19 import static java.lang.annotation.ElementType.METHOD;
20 import static java.lang.annotation.ElementType.PACKAGE;
21 import static java.lang.annotation.ElementType.TYPE;
22
23 import java.lang.annotation.Documented;
24 import java.lang.annotation.Retention;
25 import java.lang.annotation.RetentionPolicy;
26 import java.lang.annotation.Target;
27
28 /**
29 * Indicates that the annotated element and the code transitively {@linkplain
30 * javax.lang.model.element.Element#getEnclosedElements() enclosed} within it is <b>null-unmarked
31 * code</b>: there, type usages generally have <b>unspecified nullness</b> unless explicitly
32 * annotated otherwise.
33 *
34 * <p>This annotation's purpose is to ease migration of a large existing codebase to null-marked
35 * status. It makes it possible to "flip the default" for new code added to a class or package even
36 * before that class or package has been fully migrated. Since new code is the most important code
37 * to analyze, this is strongly recommended as a temporary measure whenever necessary. However, once
38 * a codebase has been fully migrated it would be appropriate to ban use of this annotation.
39 *
40 * <p>For a comprehensive introduction to JSpecify, please see <a
41 * href="http://jspecify.org">jspecify.org</a>.
42 *
43 * <h2>Null-marked and null-unmarked code</h2>
44 *
45 * <p>{@link NullMarked} and this annotation work as a pair to include and exclude sections of code
46 * from null-marked status (respectively). Specifically, code is considered null-marked if the most
47 * narrowly enclosing element annotated with either of these two annotations exists and is annotated
48 * with {@code @NullMarked}.
49 *
50 * <p>Otherwise it is considered null-unmarked. This can happen in two ways: either it is more
51 * narrowly enclosed by a {@code @NullUnmarked}-annotated element than by any
52 * {@code @NullMarked}-annotated element, or neither annotation is present on any enclosing element.
53 * No distinction is made between these cases.
54 *
55 * <p>The effects of being null-marked are described in the <a
56 * href="NullMarked.html#effects">Effects</a> section of {@code NullMarked}.
57 *
58 * <h2>Unspecified nullness</h2>
59 *
60 * <p>Within null-unmarked code, a type usage with no nullness annotation has <b>unspecified
61 * nullness</b> (<a href="https://bit.ly/3ppb8ZC">Why?</a>). This means that, while there is always
62 * <i>some</i> correct way to annotate it for nullness, that information is missing: we <i>do not
63 * know</i> whether it includes or excludes {@code null} as a value. In such a case, tools can vary
64 * widely in how strict or lenient their enforcement is, or might make it configurable.
65 *
66 * <p>For more, please see this more <a
67 * href="https://github.com/jspecify/jspecify/wiki/nullness-unspecified">comprehensive
68 * discussion</a> of unspecified nullness.
69 *
70 * <p>There is no way for an individual type usage within null-marked code to have unspecified
71 * nullness. (<a href="https://bit.ly/3ppb8ZC">Why?</a>)
72 *
73 * <h2>Where it can be used</h2>
74 *
75 * The information in the <a href="NullMarked.html#where">Where it can be used</a> section of {@code
76 * NullMarked} applies as well to this annotation.
77 */
78 // TODO(kevinb9n): word the middle section better with good words
79 @Documented
80 @Retention(RetentionPolicy.RUNTIME)
81 @Target({PACKAGE, TYPE, METHOD, CONSTRUCTOR})
82 public @interface NullUnmarked {}