Expand @UnmodParam => @UnmodifiableParam

mernst · mernst · commit 4afa7a6d7383 · 2026-05-24T03:16:46.000-07:00
diff --git a/buildSrc/src/main/groovy/cf-spotless.gradle b/buildSrc/src/main/groovy/cf-spotless.gradle
@@ -111,7 +111,7 @@ spotless {
         .addTypeAnnotation("MaybeReplaceable")
         .addTypeAnnotation("MaybeShrinkable")
         .addTypeAnnotation("Unmodifiable")
-        .addTypeAnnotation("UnmodParam")
+        .addTypeAnnotation("UnmodifiableParam")
         .addTypeAnnotation("Unreplaceable")
         .addTypeAnnotation("Unshrinkable")
   }
diff --git a/checker-qual/src/main/java/org/checkerframework/checker/modifiability/qual/UnmodifiableParam.java b/checker-qual/src/main/java/org/checkerframework/checker/modifiability/qual/UnmodifiableParam.java
@@ -20,4 +20,4 @@
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
-public @interface UnmodParam {}
+public @interface UnmodifiableParam {}
diff --git a/checker/src/main/java/org/checkerframework/checker/modifiability/ModifiabilityVisitor.java b/checker/src/main/java/org/checkerframework/checker/modifiability/ModifiabilityVisitor.java
@@ -12,7 +12,7 @@
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.type.TypeMirror;
 import org.checkerframework.checker.modifiability.qual.ThrowsUOE;
-import org.checkerframework.checker.modifiability.qual.UnmodParam;
+import org.checkerframework.checker.modifiability.qual.UnmodifiableParam;
 import org.checkerframework.common.basetype.BaseAnnotatedTypeFactory;
 import org.checkerframework.common.basetype.BaseTypeChecker;
 import org.checkerframework.common.basetype.BaseTypeVisitor;
@@ -75,8 +75,8 @@ public void processClassTree(ClassTree classTree) {
 
   @Override
   public Void visitAnnotation(AnnotationTree tree, Void p) {
-    if (shouldCheckUnmodParamLocation() && isUnmodParamAnnotation(tree)) {
-      if (!isWithinAllowedUnmodParamLocation()) {
+    if (shouldCheckUnmodifiableParamLocation() && isUnmodifiableParamAnnotation(tree)) {
+      if (!isWithinAllowedUnmodifiableParamLocation()) {
         checker.reportError(tree, "unmodparam.location");
       }
     }
@@ -114,14 +114,14 @@ protected boolean shouldCheckThrowsUOE() {
   }
 
   /**
-   * Returns true if this checker should report {@code @UnmodParam} location errors.
+   * Returns true if this checker should report {@code @UnmodifiableParam} location errors.
    *
    * <p>The default is {@code true}. Shrink and Replace override this to avoid tripling diagnostics
    * when running under the aggregate {@link ModifiabilityChecker}.
    *
-   * @return true if this visitor should report {@code @UnmodParam} location errors
+   * @return true if this visitor should report {@code @UnmodifiableParam} location errors
    */
-  protected boolean shouldCheckUnmodParamLocation() {
+  protected boolean shouldCheckUnmodifiableParamLocation() {
     return true;
   }
 
@@ -139,30 +139,31 @@ protected boolean shouldCheckCustomModifiabilityAnnotation() {
   }
 
   /**
-   * Returns true if {@code tree} is an {@link UnmodParam} annotation.
+   * Returns true if {@code tree} is an {@link UnmodifiableParam} annotation.
    *
    * @param tree an annotation tree
-   * @return true if {@code tree} is an {@code @UnmodParam} annotation
+   * @return true if {@code tree} is an {@code @UnmodifiableParam} annotation
    */
-  private boolean isUnmodParamAnnotation(AnnotationTree tree) {
+  private boolean isUnmodifiableParamAnnotation(AnnotationTree tree) {
     String annotationName = tree.getAnnotationType().toString();
     // Quick check to avoid expensive annotation resolution for most annotations.
-    if (!annotationName.equals("UnmodParam") && !annotationName.endsWith(".UnmodParam")) {
+    if (!annotationName.equals("UnmodifiableParam")
+        && !annotationName.endsWith(".UnmodifiableParam")) {
       return false;
     }
 
     AnnotationMirror annotation = TreeUtils.annotationFromAnnotationTree(tree);
-    return annotation != null && atypeFactory.areSameByClass(annotation, UnmodParam.class);
+    return annotation != null && atypeFactory.areSameByClass(annotation, UnmodifiableParam.class);
   }
 
   /**
    * Returns true if the current annotation path is inside a method/constructor parameter type or
    * explicit receiver parameter type.
    *
-   * @return true if {@code @UnmodParam} is allowed at the current location
+   * @return true if {@code @UnmodifiableParam} is allowed at the current location
    */
   @SuppressWarnings("interning:not.interned") // AST node comparison
-  private boolean isWithinAllowedUnmodParamLocation() {
+  private boolean isWithinAllowedUnmodifiableParamLocation() {
     // Find the declaration that contains the annotation, if any.
     TreePath path = getCurrentPath();
     TreePath variablePath = null;
diff --git a/checker/src/main/java/org/checkerframework/checker/modifiability/grow/GrowAnnotatedTypeFactory.java b/checker/src/main/java/org/checkerframework/checker/modifiability/grow/GrowAnnotatedTypeFactory.java
@@ -22,8 +22,8 @@
 import org.checkerframework.checker.modifiability.qual.PolyGrowable;
 import org.checkerframework.checker.modifiability.qual.PolyModifiable;
 import org.checkerframework.checker.modifiability.qual.Ungrowable;
-import org.checkerframework.checker.modifiability.qual.UnmodParam;
 import org.checkerframework.checker.modifiability.qual.Unmodifiable;
+import org.checkerframework.checker.modifiability.qual.UnmodifiableParam;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.checkerframework.common.basetype.BaseAnnotatedTypeFactory;
 import org.checkerframework.common.basetype.BaseTypeChecker;
@@ -125,7 +125,7 @@ public AnnotationMirror canonicalAnnotation(
     } else if (areSameByClass(annotation, Unmodifiable.class)) {
       return tm != null && typeCannotGrow(tm) ? MAYBE_GROW : UNGROWABLE;
     } else if (areSameByClass(annotation, MaybeModifiable.class)
-        || areSameByClass(annotation, UnmodParam.class)) {
+        || areSameByClass(annotation, UnmodifiableParam.class)) {
       return MAYBE_GROW;
     } else if (areSameByClass(annotation, PolyModifiable.class)) {
       return tm != null && isMapEntry(tm) ? MAYBE_GROW : POLY_GROW;
diff --git a/checker/src/main/java/org/checkerframework/checker/modifiability/replace/ReplaceAnnotatedTypeFactory.java b/checker/src/main/java/org/checkerframework/checker/modifiability/replace/ReplaceAnnotatedTypeFactory.java
@@ -21,8 +21,8 @@
 import org.checkerframework.checker.modifiability.qual.PolyModifiable;
 import org.checkerframework.checker.modifiability.qual.PolyReplaceable;
 import org.checkerframework.checker.modifiability.qual.Replaceable;
-import org.checkerframework.checker.modifiability.qual.UnmodParam;
 import org.checkerframework.checker.modifiability.qual.Unmodifiable;
+import org.checkerframework.checker.modifiability.qual.UnmodifiableParam;
 import org.checkerframework.checker.modifiability.qual.Unreplaceable;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.checkerframework.common.basetype.BaseAnnotatedTypeFactory;
@@ -140,7 +140,7 @@ public AnnotationMirror canonicalAnnotation(
     } else if (areSameByClass(annotation, Unmodifiable.class)) {
       return tm != null && typeCannotReplace(tm) ? MAYBE_REPLACE : UNREPLACEABLE;
     } else if (areSameByClass(annotation, MaybeModifiable.class)
-        || areSameByClass(annotation, UnmodParam.class)) {
+        || areSameByClass(annotation, UnmodifiableParam.class)) {
       return MAYBE_REPLACE;
     } else if (areSameByClass(annotation, PolyModifiable.class)) {
       return POLY_REPLACE;
diff --git a/checker/src/main/java/org/checkerframework/checker/modifiability/replace/ReplaceVisitor.java b/checker/src/main/java/org/checkerframework/checker/modifiability/replace/ReplaceVisitor.java
@@ -22,8 +22,9 @@ protected boolean shouldCheckThrowsUOE() {
   }
 
   @Override
-  protected boolean shouldCheckUnmodParamLocation() {
-    // When running under ModifiabilityChecker, GrowChecker handles @UnmodParam location reporting.
+  protected boolean shouldCheckUnmodifiableParamLocation() {
+    // When running under ModifiabilityChecker, GrowChecker handles @UnmodifiableParam location
+    // reporting.
     return checker.getParentChecker() == null;
   }
 
diff --git a/checker/src/main/java/org/checkerframework/checker/modifiability/shrink/ShrinkAnnotatedTypeFactory.java b/checker/src/main/java/org/checkerframework/checker/modifiability/shrink/ShrinkAnnotatedTypeFactory.java
@@ -21,8 +21,8 @@
 import org.checkerframework.checker.modifiability.qual.PolyModifiable;
 import org.checkerframework.checker.modifiability.qual.PolyShrinkable;
 import org.checkerframework.checker.modifiability.qual.Shrinkable;
-import org.checkerframework.checker.modifiability.qual.UnmodParam;
 import org.checkerframework.checker.modifiability.qual.Unmodifiable;
+import org.checkerframework.checker.modifiability.qual.UnmodifiableParam;
 import org.checkerframework.checker.modifiability.qual.Unshrinkable;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.checkerframework.common.basetype.BaseAnnotatedTypeFactory;
@@ -122,7 +122,7 @@ public AnnotationMirror canonicalAnnotation(
     } else if (areSameByClass(annotation, Unmodifiable.class)) {
       return tm != null && typeCannotShrink(tm) ? MAYBE_SHRINK : UNSHRINKABLE;
     } else if (areSameByClass(annotation, MaybeModifiable.class)
-        || areSameByClass(annotation, UnmodParam.class)) {
+        || areSameByClass(annotation, UnmodifiableParam.class)) {
       return MAYBE_SHRINK;
     } else if (areSameByClass(annotation, PolyModifiable.class)) {
       return tm != null && isMapEntry(tm) ? MAYBE_SHRINK : POLY_SHRINK;
diff --git a/checker/src/main/java/org/checkerframework/checker/modifiability/shrink/ShrinkVisitor.java b/checker/src/main/java/org/checkerframework/checker/modifiability/shrink/ShrinkVisitor.java
@@ -22,8 +22,9 @@ protected boolean shouldCheckThrowsUOE() {
   }
 
   @Override
-  protected boolean shouldCheckUnmodParamLocation() {
-    // When running under ModifiabilityChecker, GrowChecker handles @UnmodParam location reporting.
+  protected boolean shouldCheckUnmodifiableParamLocation() {
+    // When running under ModifiabilityChecker, GrowChecker handles @UnmodifiableParam location
+    // reporting.
     return checker.getParentChecker() == null;
   }
 
diff --git a/checker/src/main/resources/org/checkerframework/checker/modifiability/messages.properties b/checker/src/main/resources/org/checkerframework/checker/modifiability/messages.properties
@@ -1,3 +1,3 @@
 usage.throws.uoe=Call to %s will always throw UnsupportedOperationException.
-unmodparam.location=@UnmodParam may only be written on method/constructor parameters or explicit receiver parameters.
+unmodparam.location=@UnmodifiableParam may only be written on method/constructor parameters or explicit receiver parameters.
 modifiability.annotation.unverified=Modifiability annotations/defaults on source-defined collection/map/iterator type %s are trusted but not verified by the checker; manually verify them and suppress this warning if correct.
diff --git a/checker/tests/modifiability/BasicModifiabilityTest.java b/checker/tests/modifiability/BasicModifiabilityTest.java
@@ -4,8 +4,8 @@
 import org.checkerframework.checker.modifiability.qual.IteratorPolyMod;
 import org.checkerframework.checker.modifiability.qual.MaybeModifiable;
 import org.checkerframework.checker.modifiability.qual.Modifiable;
-import org.checkerframework.checker.modifiability.qual.UnmodParam;
 import org.checkerframework.checker.modifiability.qual.Unmodifiable;
+import org.checkerframework.checker.modifiability.qual.UnmodifiableParam;
 
 // this checkes the correctness of annotation in List.java and ONLY the initialization of ArrayList
 public class BasicModifiabilityTest {
@@ -102,7 +102,7 @@ void testMutatingBulkOperations(@Modifiable List<String> mod, @Unmodifiable List
     unmod.retainAll(other);
   }
 
-  void testUnmodParamMutation(@UnmodParam List<String> unmodParam, String value) {
+  void testUnmodifiableParamMutation(@UnmodifiableParam List<String> unmodParam, String value) {
     // :: error: [method.invocation]
     unmodParam.add(value);
     // :: error: [method.invocation]
diff --git a/checker/tests/modifiability/UnmodParamLocationTest.java b/checker/tests/modifiability/UnmodParamLocationTest.java
@@ -1,47 +1,47 @@
 import java.util.List;
 import java.util.function.Consumer;
-import org.checkerframework.checker.modifiability.qual.UnmodParam;
+import org.checkerframework.checker.modifiability.qual.UnmodifiableParam;
 
 class UnmodParamLocationTest<
     // :: error: [unmodparam.location]
-    @UnmodParam T> {
+    @UnmodifiableParam T> {
 
   // :: error: [unmodparam.location]
-  @UnmodParam List<String> field;
+  @UnmodifiableParam List<String> field;
 
   // :: error: [unmodparam.location]
-  List<@UnmodParam List<String>> nestedField;
+  List<@UnmodifiableParam List<String>> nestedField;
 
-  UnmodParamLocationTest(@UnmodParam List<String> parameter) {}
+  UnmodParamLocationTest(@UnmodifiableParam List<String> parameter) {}
 
-  void method(@UnmodParam List<String> parameter) {}
+  void method(@UnmodifiableParam List<String> parameter) {}
 
-  void nestedParameter(List<@UnmodParam List<String>> parameter) {}
+  void nestedParameter(List<@UnmodifiableParam List<String>> parameter) {}
 
-  void receiver(@UnmodParam UnmodParamLocationTest<T> this) {}
+  void receiver(@UnmodifiableParam UnmodParamLocationTest<T> this) {}
 
   // :: error: [unmodparam.location]
-  @UnmodParam List<String> returnType() {
+  @UnmodifiableParam List<String> returnType() {
     return null;
   }
 
   @SuppressWarnings("unchecked")
   void local(Object object) {
     // :: error: [unmodparam.location]
-    @UnmodParam List<String> local = null;
+    @UnmodifiableParam List<String> local = null;
     local = null;
 
     // :: error: [unmodparam.location]
-    List<String> cast = (@UnmodParam List<String>) object;
+    List<String> cast = (@UnmodifiableParam List<String>) object;
     cast = null;
   }
 
   void lambda() {
     // :: error: [unmodparam.location]
-    Consumer<List<String>> consumer = (@UnmodParam List<String> parameter) -> {};
+    Consumer<List<String>> consumer = (@UnmodifiableParam List<String> parameter) -> {};
     consumer.accept(null);
   }
 
   // :: error: [unmodparam.location]
-  <@UnmodParam S> void methodTypeParameter(S value) {}
+  <@UnmodifiableParam S> void methodTypeParameter(S value) {}
 }
diff --git a/docs/manual/modifiability-checker.tex b/docs/manual/modifiability-checker.tex
@@ -135,12 +135,12 @@
 The checker conservatively issues a warning at every invocation of a grow,
 shrink, or replace operation.
 
-\item[\refqualclass{checker/modifiability/qual}{UnmodParam}]
+\item[\refqualclass{checker/modifiability/qual}{UnmodifiableParam}]
 A syntactic sugar for \refqualclass{checker/modifiability/qual}{MaybeModifiable}.
 It may only be written within a method or constructor parameter type, or within
 an explicit receiver parameter type, when the method is not designed to change
 the parameter.  It may appear nested within such a parameter type, such as in
-\code{List<@UnmodParam List<String>>}.
+\code{List<@UnmodifiableParam List<String>>}.
 
 \item[\refqualclass{checker/modifiability/qual}{PolyModifiable}]
 Alias for \code{@PolyGrowable @PolyShrinkable @PolyReplaceable}
@@ -155,7 +155,7 @@
   @Modifiable List<String> mod = new ArrayList<>();  // all three capabilities
   @Unmodifiable List<String> unmod = List.of("a");   // no capabilities
   @MaybeModifiable List<String> unknown = ...;  // capabilities are unknown at compile time
-  void foo(@UnmodParam List<String> list) { ... }  // foo does not modify list
+  void foo(@UnmodifiableParam List<String> list) { ... }  // foo does not modify list
 \end{Verbatim}
 
 \subsectionAndLabel{Hierarchy qualifiers}{modifiability-hierarchy-qualifiers}
@@ -446,7 +446,7 @@
 % LocalWords:  Modifiability modifiability copyOf emptyList emptySet gsr
 % LocalWords:  emptyMap unmodifiableList unmodifiableSet unmodifiableMap
 % LocalWords:  toArray addAll removeAll retainAll replaceAll setValue
-% LocalWords:  MaybeModifiable UnmodParam Growable MaybeGrowable MaybeShrinkable
+% LocalWords:  MaybeModifiable UnmodifiableParam Growable MaybeGrowable MaybeShrinkable
 % LocalWords:  MaybeReplaceable growable ListIterator PolyModifiable addFirst
 % LocalWords:  synchronizedList PolyShrinkable PolyGrowable PolyReplaceable ThrowsUOE
 % LocalWords:  addLast unreplaceable Growability shrinkability replacability

Original file line number	Diff line number	Diff line change
`@@ -111,7 +111,7 @@ spotless {`
`111`	`111`	`.addTypeAnnotation("MaybeReplaceable")`
`112`	`112`	`.addTypeAnnotation("MaybeShrinkable")`
`113`	`113`	`.addTypeAnnotation("Unmodifiable")`
`114`		`- .addTypeAnnotation("UnmodParam")`
	`114`	`+ .addTypeAnnotation("UnmodifiableParam")`
`115`	`115`	`.addTypeAnnotation("Unreplaceable")`
`116`	`116`	`.addTypeAnnotation("Unshrinkable")`
`117`	`117`	`}`
Original file line number	Diff line number	Diff line change
`@@ -22,8 +22,9 @@ protected boolean shouldCheckThrowsUOE() {`
`22`	`22`	`}`
`23`	`23`
`24`	`24`	`@Override`
`25`		`- protected boolean shouldCheckUnmodParamLocation() {`
`26`		`- // When running under ModifiabilityChecker, GrowChecker handles @UnmodParam location reporting.`
	`25`	`+ protected boolean shouldCheckUnmodifiableParamLocation() {`
	`26`	`+ // When running under ModifiabilityChecker, GrowChecker handles @UnmodifiableParam location`
	`27`	`+ // reporting.`
`27`	`28`	`return checker.getParentChecker() == null;`
`28`	`29`	`}`
`29`	`30`