Skip to content

Commit f01eac9

Browse files
authored
batch of javadoc revisions for clarity and completeness (#671)
Extensive overhaul of annotation javadoc for clarity and correctness - no actual spec changes. Improves how we address things like generics, arrays, record components, applicability edge cases, inclusion-exclusion, and I suppose a lot more.
1 parent c4eff31 commit f01eac9

7 files changed

Lines changed: 164 additions & 166 deletions

File tree

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,10 @@ local.properties
7777
.idea/**/usage.statistics.xml
7878
.idea/**/dictionaries
7979
.idea/**/shelf
80+
.idea/**/*.iml
81+
.gradle-user/
82+
.idea/codeStyles/
83+
.idea/inspectionProfiles/
8084

8185
# AWS User-specific
8286
.idea/**/aws.xml

‎AUTHORS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@
44
# some cases, their employer may be the copyright holder. To see the full list
55
# of contributors, see the revision history in source control.
66
Google LLC
7+
Oracle America, Inc.
78
SpotBugs Team

‎src/main/java/org/jspecify/annotations/NonNull.java‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,19 @@
2525
/**
2626
* Indicates that the annotated <a href="https://github.com/jspecify/jspecify/wiki/type-usages">type
2727
* usage</a> (commonly a parameter type or return type) is considered to <i>exclude</i> {@code null}
28-
* as a value; rarely needed within {@linkplain NullMarked null-marked} code.
28+
* as a value; rarely needed within {@linkplain NullMarked null-marked} context.
2929
*
3030
* <p>This annotation serves two primary purposes:
3131
*
3232
* <ul>
3333
* <li>To mark any sporadic non-null type usages inside a scope that is not ready to be fully
34-
* {@link NullMarked} yet.
34+
* null-marked yet.
3535
* <li>To perform a <i>non-null projection</i> of a type variable, explained below.
3636
* </ul>
3737
*
38-
* <p>For a comprehensive introduction to JSpecify, please see <a
39-
* href="https://jspecify.dev">jspecify.org</a>.
38+
* <p>For important information common to all four nullness annotations, see {@link
39+
* org.jspecify.annotations}. To learn more about JSpecify, see <a
40+
* href="https://jspecify.dev">jspecify.dev</a>.
4041
*
4142
* <h2 id="projection">Non-null projection</h2>
4243
*
@@ -45,7 +46,7 @@
4546
* nullable type argument.
4647
*
4748
* <pre>{@code
48-
* // All the below is null-marked code
49+
* // Everything below is in null-marked context:
4950
*
5051
* class MyOptional<T> { … }
5152
*
@@ -87,8 +88,8 @@
8788
*
8889
* <h2>Where it is applicable</h2>
8990
*
90-
* <p>{@code @NonNull} is applicable in all the {@linkplain Nullable##applicability same locations}
91-
* as {@link Nullable}.
91+
* <p>This annotation is applicable in all the {@linkplain Nullable##applicability same locations}
92+
* as {@code Nullable}.
9293
*/
9394
@Documented
9495
@Target(TYPE_USE)

‎src/main/java/org/jspecify/annotations/NullMarked.java‎

Lines changed: 46 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -28,84 +28,71 @@
2828

2929
/**
3030
* 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.
3535
*
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>.
3844
*
3945
* <h2 id="effects">Effects of being null-marked</h2>
4046
*
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.
4449
*
4550
* <h3 id="effects-special-cases">Special cases</h3>
4651
*
47-
* <p>Within null-marked code:
52+
* <p>Within null-marked context:
4853
*
4954
* <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
5762
* 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.
7970
* </ul>
8071
*
8172
* <h2 id="where">Where it can be used</h2>
8273
*
8374
* {@code @NullMarked} and {@link NullUnmarked @NullUnmarked} can be used on any package, class,
8475
* 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:
8778
*
8879
* <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
9081
* 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.
10996
* <li>If both {@code @NullMarked} and {@code @NullUnmarked} appear together on the same element,
11097
* <i>neither</i> one is recognized.
11198
* </ul>

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

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -27,55 +27,56 @@
2727

2828
/**
2929
* 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.
30+
* javax.lang.model.element.Element#getEnclosedElements() enclosed} within it are in
31+
* <b>null-unmarked context</b>: there, type usages generally have {@linkplain ##unspecified
32+
* unspecified nullness} unless explicitly annotated otherwise.
3333
*
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.
34+
* <p>This annotation's purpose is to ease progressive migration of a large codebase. If some class
35+
* or package can't be fully migrated yet, you can still make it {@linkplain NullMarked null-marked}
36+
* by using this annotation on the portions that still need work. This practice is useful because it
37+
* flips the default for <i>new</i> code added later, which is the most important code to analyze.
3938
*
40-
* <p>For a comprehensive introduction to JSpecify, please see <a
41-
* href="https://jspecify.dev">jspecify.org</a>.
39+
* <p>Once a codebase has been fully migrated it would be reasonable to ban use of this annotation.
4240
*
43-
* <h2>Null-marked and null-unmarked code</h2>
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>.
4444
*
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}.
45+
* <h2>Null-marked and null-unmarked contexts</h2>
4946
*
50-
* <p>Otherwise it is considered null-unmarked. This can happen in two ways: either it is more
47+
* <p>{@link NullMarked} puts enclosed code in null-marked context; this annotation puts it in
48+
* null-unmarked context instead. These annotations work as an inclusion-exclusion pair: of the
49+
* annotations of <i>either</i> type on all enclosing elements (methods, classes, etc.), only the
50+
* <i>nearest</i> (most narrowly enclosing) one is in effect.
51+
*
52+
* <p>Otherwise, code is in null-unmarked context. This can happen in two ways: either it is more
5153
* narrowly enclosed by a {@code @NullUnmarked}-annotated element than by any
5254
* {@code @NullMarked}-annotated element, or neither annotation is present on any enclosing element.
5355
* No distinction is made between these cases.
5456
*
5557
* <p>The effects of being null-marked are described in the {@linkplain NullMarked##effects Effects}
5658
* section of {@code NullMarked}.
5759
*
58-
* <h2>Unspecified nullness</h2>
60+
* <h2 id="unspecified">Unspecified nullness</h2>
5961
*
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.
62+
* <p>Within null-unmarked context, a type usage that is {@linkplain Nullable##applicability
63+
* nullness-applicable} but has no nullness annotation generally has <b>unspecified nullness</b> (<a
64+
* href="https://bit.ly/3ppb8ZC">Why?</a>). This means we <i>do not know</i> whether it includes or
65+
* excludes {@code null} as a value. In such a case, tools can vary widely in how strict or lenient
66+
* their enforcement is, or might even be configurable.
6567
*
6668
* <p>For more, please see this more <a
6769
* href="https://github.com/jspecify/jspecify/wiki/nullness-unspecified">comprehensive
6870
* discussion</a> of unspecified nullness.
6971
*
70-
* <p>There is no way for an individual type usage within null-marked code to have unspecified
72+
* <p>There is no way for an individual type usage within null-marked context to have unspecified
7173
* nullness. (<a href="https://bit.ly/3ppb8ZC">Why?</a>)
7274
*
7375
* <h2>Where it can be used</h2>
7476
*
7577
* The information in the {@linkplain NullMarked##where Where it can be used} section of {@code
7678
* NullMarked} applies as well to this annotation.
7779
*/
78-
// TODO(kevinb9n): word the middle section better with good words
7980
@Documented
8081
@Retention(RetentionPolicy.RUNTIME)
8182
@Target({PACKAGE, TYPE, METHOD, CONSTRUCTOR})

0 commit comments

Comments
 (0)