| 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 {} |