Allow NotNull and Nullable on package declarations

CHANGELOG.md

@@ -1,6 +1,10 @@
 Changelog
 ===
 
+Version 22.1.0
+---
+* Allow `@NotNull` and `@Nullable` on package declarations.
+
 Version 22.0.0
 ---
 * Added new annotations: `@Blocking` and `@NonBlocking`.

common/src/main/java/org/jetbrains/annotations/NotNull.java

@@ -19,14 +19,16 @@
 import java.lang.annotation.*;
 
 /**
- * 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).
+ * An element annotated with {@link NotNull} claims {@code null} value is <em>forbidden</em>
+ * to return (for methods), pass to (parameters) and hold (local variables and fields). When a
+ * package is annotated with {@link NotNull} it claims that all fields and the return value for
+ * methods in every class of this package are non-nullable by default.
  * 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.
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)
-@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE_USE})
+@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE_USE, ElementType.PACKAGE})
 public @interface NotNull {
   /**
    * @return Custom exception message

common/src/main/java/org/jetbrains/annotations/Nullable.java

@@ -20,7 +20,9 @@
 
 /**
  * An element annotated with {@link Nullable} claims {@code null} value is perfectly <em>valid</em>
- * to return (for methods), pass to (parameters) or hold in (local variables and fields).
+ * to return (for methods), pass to (parameters) or hold in (local variables and fields). When a package
+ * is annotated with {@link Nullable} it claims that all fields and the return value for methods in every
+ * class of this package are nullable by default.
  * 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>
@@ -36,7 +38,7 @@
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)
-@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE_USE})
+@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE_USE, ElementType.PACKAGE})
 public @interface Nullable {
   /**
    * @return textual reason when the annotated value could be null, for documentation purposes.

gradle.properties

@@ -14,5 +14,5 @@
 # limitations under the License.
 #
 
-projectVersion=22.0.0
+projectVersion=22.1.0
 #JDK_5=<path-to-older-java-version>