* Apart from documentation purposes this annotation is intended to be used by static analysis tools * to validate against probable runtime errors and element contract violations. + *
+ * If a field is annotated as {@code @NotNull} it's expected to be initialized during object construction. + * Tools may issue a warning if it's not the case. + *
+ * If a method overrides a superclass method, and the superclass method specifies the nullability on parameter + * or return type, then the subclass method should specify the same nullability, either directly or indirectly + * via {@link @NotNullByDefault}. The only exception is the covariant return type nullability: if the superclass + * method is declared to return nullable value, then subclass may declare to return a not-null value. + *
+ * The tools may issue a warning if the nullability for a subclass method contradicts from the specified nullability + * of a superclass method. + * + * @see Nullable */ @Documented @Retention(RetentionPolicy.CLASS) @@ -36,7 +50,7 @@ /** * @return Custom exception type that should be thrown when not-nullity contract is violated. * The exception class should have a constructor with one String argument (message). - * + *
* By default, {@link IllegalArgumentException} is thrown on null method arguments and * {@link IllegalStateException} — on null return value. */ diff --git a/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java b/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java index 24f8e39..0caaaf6 100644 --- a/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java +++ b/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java @@ -13,8 +13,13 @@ * Recursively not-null means that along with types themselves, the components of array types, the type arguments * of generic types and the upper bounds of wildcard types are also not-null. *
- * The annotation has no effect on overridden method parameters and return values. In this case, the annotations - * declared on the original method in the superclass or interface take place. + * If a method overrides a superclass method, and the superclass method specifies the nullability on parameter + * or return type, then the subclass method should specify the same nullability, either directly or indirectly + * via {@code @NotNullByDefault}. The only exception is the covariant return type nullability: if the superclass + * method is declared to return nullable value, then subclass may declare to return a not-null value. + *
+ * The tools may issue a warning if the nullability for a subclass method contradicts from the specified nullability + * of a superclass method. *
* The annotation has no effect on newly declared type parameters and their bounds. Only instantiations of * type parameters are constrained. @@ -22,7 +27,7 @@ * The annotation has no effect on local variables. * * @see NotNull - * @since 25.0.0 + * @since 26.0.0 */ @Documented @Retention(RetentionPolicy.CLASS) diff --git a/src/jvmMain/java/org/jetbrains/annotations/Nullable.java b/src/jvmMain/java/org/jetbrains/annotations/Nullable.java index 8d9e497..a00a68d 100644 --- a/src/jvmMain/java/org/jetbrains/annotations/Nullable.java +++ b/src/jvmMain/java/org/jetbrains/annotations/Nullable.java @@ -19,20 +19,31 @@ import java.lang.annotation.*; /** - * An element annotated with {@link Nullable} claims {@code null} value is perfectly valid + * An element annotated with {@code Nullable} claims {@code null} value is perfectly valid * to return (for methods), pass to (parameters) or hold in (local variables and fields). * Apart from documentation purposes this annotation is intended to be used by static analysis tools * to validate against probable runtime errors or element contract violations. *
* By convention, this annotation applied only when the value should always be checked against {@code null} * because the developer could do nothing to prevent null from happening. - * Otherwise, too eager {@link Nullable} usage could lead to too many false positives from static analysis tools. + * Otherwise, too eager {@code Nullable} usage could lead to too many false positives from static analysis tools. *
- * For example, {@link java.util.Map#get(Object key)} should not be annotated {@link Nullable} because + * For example, {@link java.util.Map#get(Object key)} should not be annotated {@code Nullable} because * someone may have put not-null value in the map by this key and is expecting to find this value there ever since. + * It could be annotated as {@link UnknownNullability} or left unannotated. *
- * On the other hand, the {@link java.lang.ref.Reference#get()} should be annotated {@link Nullable} because + * On the other hand, the {@link java.lang.ref.Reference#get()} should be annotated {@code Nullable} because * it returns {@code null} if object got collected which can happen at any time completely unexpectedly. + *
+ * If a method overrides a superclass method, and the superclass method specifies the nullability on parameter + * or return type, then the subclass method should specify the same nullability, either directly or indirectly + * via {@link @NotNullByDefault}. The only exception is the covariant return type nullability: if the superclass + * method is declared to return nullable value, then subclass may declare to return a not-null value. + *
+ * The tools may issue a warning if the nullability for a subclass method contradicts from the specified nullability + * of a superclass method. + * + * @see NotNull */ @Documented @Retention(RetentionPolicy.CLASS) diff --git a/src/jvmMain/java/org/jetbrains/annotations/UnknownNullability.java b/src/jvmMain/java/org/jetbrains/annotations/UnknownNullability.java index 1dd5a0a..79e026b 100644 --- a/src/jvmMain/java/org/jetbrains/annotations/UnknownNullability.java +++ b/src/jvmMain/java/org/jetbrains/annotations/UnknownNullability.java @@ -23,7 +23,7 @@ import java.lang.annotation.Target; /** - * An element annotated with {@link UnknownNullability} claims that no specific nullability + * An element annotated with {@code UnknownNullability} claims that no specific nullability * should be assumed by static analyzer. The unconditional dereference of the annotated value * should not trigger a static analysis warning by default (though static analysis tool may have * an option to perform stricter analysis and issue warnings for {@code @UnknownNullability} as well). @@ -34,7 +34,9 @@ * The {@code UnknownNullability} is the default nullability for unannotated methods, so it's * rarely necessary. An explicit annotation may serve to document the method behavior and also * to override automatic annotation inference result that could be implemented in some static - * analysis tools. + * analysis tools. Finally, it can override the effect of {@link NotNullByDefault}. + * + * @since 21.0.0 */ @Documented @Retention(RetentionPolicy.CLASS)