jspecify · cpovirk · Oct 2, 2020 · Sep 29, 2020 · Sep 29, 2020 · Sep 30, 2020
diff --git a/samples/AnnotatedInnerOfNonParameterized.java b/samples/AnnotatedInnerOfNonParameterized.java
@@ -27,23 +27,23 @@ class DoublyNested {}
 
   @Nullable Nested x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable AnnotatedInnerOfNonParameterized.Nested x5;
 
   AnnotatedInnerOfNonParameterized.@Nullable Nested x6;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable AnnotatedInnerOfNonParameterized.Nested.DoublyNested x7;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   AnnotatedInnerOfNonParameterized.@Nullable Nested.DoublyNested x8;
 
   AnnotatedInnerOfNonParameterized.Nested.@Nullable DoublyNested x9;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<@Nullable AnnotatedInnerOfNonParameterized.Nested.DoublyNested> l1;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<AnnotatedInnerOfNonParameterized.@Nullable Nested.DoublyNested> l2;
 
   Lib<AnnotatedInnerOfNonParameterized.Nested.DoublyNested> l3;

diff --git a/samples/AnnotatedInnerOfParameterized.java b/samples/AnnotatedInnerOfParameterized.java
@@ -27,23 +27,23 @@ class DoublyNested {}
 
   @Nullable Nested x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable AnnotatedInnerOfParameterized<?>.Nested x5;
 
   AnnotatedInnerOfParameterized<?>.@Nullable Nested x6;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable AnnotatedInnerOfParameterized<?>.Nested.DoublyNested x7;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   AnnotatedInnerOfParameterized<?>.@Nullable Nested.DoublyNested x8;
 
   AnnotatedInnerOfParameterized<?>.Nested.@Nullable DoublyNested x9;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<@Nullable AnnotatedInnerOfParameterized<?>.Nested.DoublyNested> l1;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<AnnotatedInnerOfParameterized<?>.@Nullable Nested.DoublyNested> l2;
 
   Lib<AnnotatedInnerOfParameterized<?>.Nested.DoublyNested> l3;

diff --git a/samples/AnnotatedTypeParameter.java b/samples/AnnotatedTypeParameter.java
@@ -19,12 +19,12 @@
 
 @DefaultNonNull
 class AnnotatedTypeParameter {
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib1<@Nullable T> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib2<@Nullable T extends Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib3<@Nullable T extends @Nullable Object> {}
 }
diff --git a/samples/AnnotatedTypeParameterUnspec.java b/samples/AnnotatedTypeParameterUnspec.java
@@ -20,12 +20,12 @@
 
 @DefaultNonNull
 class AnnotatedTypeParameterUnspec {
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib1<@NullnessUnspecified T> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib2<@NullnessUnspecified T extends Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib3<@NullnessUnspecified T extends @Nullable Object> {}
 }
diff --git a/samples/AnnotatedWildcard.java b/samples/AnnotatedWildcard.java
@@ -21,18 +21,18 @@
 class AnnotatedWildcard {
   interface Lib<T extends @Nullable Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ?> x1;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? extends Object> x2;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? super Object> x3;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? extends @Nullable Object> x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? super @Nullable Object> x5;
 }
diff --git a/samples/AnnotatedWildcardUnspec.java b/samples/AnnotatedWildcardUnspec.java
@@ -22,18 +22,18 @@
 class AnnotatedWildcardUnspec {
   interface Lib<T extends @Nullable Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ?> x1;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? extends Object> x2;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? super Object> x3;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? extends @Nullable Object> x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? super @Nullable Object> x5;
 }
diff --git a/samples/MultipleAnnotations.java → samples/ConflictingAnnotations.java b/samples/MultipleAnnotations.java → samples/ConflictingAnnotations.java
@@ -20,8 +20,8 @@
 
 @DefaultNonNull
 class MultipleAnnotations {
-  // jspecify_nullness_paradox
+  // jspecify_conflicting_annotations
   @Nullable @NullnessUnspecified Object x1;
-  // jspecify_nullness_paradox
+  // jspecify_conflicting_annotations
   @NullnessUnspecified @Nullable Object x2;
 }
diff --git a/samples/NotNullAwareAnnotatedInnerOfNonParameterized.java b/samples/NotNullAwareAnnotatedInnerOfNonParameterized.java
@@ -25,23 +25,23 @@ class DoublyNested {}
 
   @Nullable Nested x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable NotNullAwareAnnotatedInnerOfNonParameterized.Nested x5;
 
   NotNullAwareAnnotatedInnerOfNonParameterized.@Nullable Nested x6;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable NotNullAwareAnnotatedInnerOfNonParameterized.Nested.DoublyNested x7;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   NotNullAwareAnnotatedInnerOfNonParameterized.@Nullable Nested.DoublyNested x8;
 
   NotNullAwareAnnotatedInnerOfNonParameterized.Nested.@Nullable DoublyNested x9;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<@Nullable NotNullAwareAnnotatedInnerOfNonParameterized.Nested.DoublyNested> l1;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<NotNullAwareAnnotatedInnerOfNonParameterized.@Nullable Nested.DoublyNested> l2;
 
   Lib<NotNullAwareAnnotatedInnerOfNonParameterized.Nested.DoublyNested> l3;

diff --git a/samples/NotNullAwareAnnotatedInnerOfParameterized.java b/samples/NotNullAwareAnnotatedInnerOfParameterized.java
@@ -25,23 +25,23 @@ class DoublyNested {}
 
   @Nullable Nested x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable NotNullAwareAnnotatedInnerOfParameterized<?>.Nested x5;
 
   NotNullAwareAnnotatedInnerOfParameterized<?>.@Nullable Nested x6;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable NotNullAwareAnnotatedInnerOfParameterized<?>.Nested.DoublyNested x7;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   NotNullAwareAnnotatedInnerOfParameterized<?>.@Nullable Nested.DoublyNested x8;
 
   NotNullAwareAnnotatedInnerOfParameterized<?>.Nested.@Nullable DoublyNested x9;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<@Nullable NotNullAwareAnnotatedInnerOfParameterized<?>.Nested.DoublyNested> l1;
 
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   Lib<NotNullAwareAnnotatedInnerOfParameterized<?>.@Nullable Nested.DoublyNested> l2;
 
   Lib<NotNullAwareAnnotatedInnerOfParameterized<?>.Nested.DoublyNested> l3;

diff --git a/samples/NotNullAwareAnnotatedTypeParameter.java b/samples/NotNullAwareAnnotatedTypeParameter.java
@@ -17,12 +17,12 @@
 import org.jspecify.annotations.Nullable;
 
 class NotNullAwareAnnotatedTypeParameter {
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib1<@Nullable T> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib2<@Nullable T extends Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib3<@Nullable T extends @Nullable Object> {}
 }
diff --git a/samples/NotNullAwareAnnotatedTypeParameterUnspec.java b/samples/NotNullAwareAnnotatedTypeParameterUnspec.java
@@ -18,12 +18,12 @@
 import org.jspecify.annotations.NullnessUnspecified;
 
 class NotNullAwareAnnotatedTypeParameterUnspec {
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib1<@NullnessUnspecified T> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib2<@NullnessUnspecified T extends Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   interface Lib3<@NullnessUnspecified T extends @Nullable Object> {}
 }
diff --git a/samples/NotNullAwareAnnotatedWildcard.java b/samples/NotNullAwareAnnotatedWildcard.java
@@ -19,18 +19,18 @@
 class NotNullAwareAnnotatedWildcard {
   interface Lib<T extends @Nullable Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ?> x1;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? extends Object> x2;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? super Object> x3;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? extends @Nullable Object> x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@Nullable ? super @Nullable Object> x5;
 }
diff --git a/samples/NotNullAwareAnnotatedWildcardUnspec.java b/samples/NotNullAwareAnnotatedWildcardUnspec.java
@@ -20,18 +20,18 @@
 class NotNullAwareAnnotatedWildcardUnspec {
   interface Lib<T extends @Nullable Object> {}
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ?> x1;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? extends Object> x2;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? super Object> x3;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? extends @Nullable Object> x4;
 
-  // jspecify_nullness_paradox
+  // jspecify_unrecognized_location
   Lib<@NullnessUnspecified ? super @Nullable Object> x5;
 }
diff --git a/samples/PrimitiveAnnotations.java b/samples/PrimitiveAnnotations.java
@@ -19,9 +19,9 @@
 
 @DefaultNonNull
 class PrimitiveAnnotations {
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable int x1;
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @Nullable int[] x2;
 
   int x3;

diff --git a/samples/PrimitiveAnnotationsUnspec.java b/samples/PrimitiveAnnotationsUnspec.java
@@ -19,9 +19,9 @@
 
 @DefaultNonNull
 class PrimitiveAnnotationsUnspec {
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @NullnessUnspecified int x1;
-  // jspecify_nullness_paradox
+  // jspecify_nullness_intrinsically_not_nullable
   @NullnessUnspecified int[] x2;
 
   int x3;

diff --git a/samples/README.md b/samples/README.md
@@ -91,7 +91,7 @@ Sample inputs demonstrate 2 cases:
 1.  JSpecify annotations are applied in a way that is
     [structurally illegal](https://docs.google.com/document/d/15NND5nBxMkZ-Us6wz3Pfbt4ODIaWaJ6JDs4w6h9kUaY/edit#heading=h.ib00ltjpj1xa).
 
-    <!-- TODO: Are we happy with the term "illegal?" If so, use it in the comment text instead of "paradox?" -->
+    <!-- TODO: Are we happy with the term "illegal?" -->
 
 2.  The second case is more nuanced: Based on JSpecify annotations and rules,
     the code's types can all be augmented with nullness information. We could
@@ -110,9 +110,20 @@ cases above.
 
 A comment on a given line provides information about the following line.
 
-Such a comment contains one of 3 special sequences:
+Such a comment contains one of 5 special sequences. The first 3 cover case 1
+from above:
 
--   `jspecify_nullness_paradox`: for case 1 above
+-   `jspecify_conflicting_annotations`: for cases like `@Nullable
+    @NullnessUnspecified Foo`
+
+-   `jspecify_unrecognized_location`: for cases like `class @Nullable Foo {}`,
+    in which JSpecify does not currently specify meaning for annotations on a
+    given location but we can imagine uses for them
+
+-   `jspecify_nullness_intrinsically_not_nullable`: for cases like `@Nullable
+    int`
+
+The remaining 2 cover case 2:
 
 -   `jspecify_nullness_mismatch`: for certain instances of case 2