Improved documentation for nullity annotations

Author: amaembo

src/jvmMain/java/org/jetbrains/annotations/NotNull.java

@@ -21,8 +21,22 @@
 /**
  * An element annotated with NotNull claims {@code null} value is <em>forbidden</em>
  * to return (for methods), pass to (parameters) and hold (local variables and fields).
+ * <p>
  * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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).
-   *
+   * <p>
    * By default, {@link IllegalArgumentException} is thrown on null method arguments and
    * {@link IllegalStateException} &mdash; on null return value.
    */

src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java

@@ -13,16 +13,21 @@
  * 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.
  * <p>
- * 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.
+ * <p>
+ * The tools may issue a warning if the nullability for a subclass method contradicts from the specified nullability
+ * of a superclass method.
  * <p>
  * The annotation has no effect on newly declared type parameters and their bounds. Only instantiations of
  * type parameters are constrained.
  * <p>
  * The annotation has no effect on local variables.
  *
  * @see NotNull
- * @since 25.0.0
+ * @since 26.0.0
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)

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 <em>valid</em>
+ * An element annotated with {@code Nullable} claims {@code null} value is perfectly <em>valid</em>
  * 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.
  * <p>
  * By convention, this annotation applied only when the value should <em>always</em> 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.
  * <p>
- * For example, {@link java.util.Map#get(Object key)} should <em>not</em> be annotated {@link Nullable} because
+ * For example, {@link java.util.Map#get(Object key)} should <em>not</em> 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.
  * <p>
- * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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)

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)