Signature annotations for Javadoc code

mernst · web-flow · commit 9411c75249da · 2020-07-27T07:32:46.000-07:00
diff --git a/README b/README
@@ -96,12 +96,12 @@ Qualifier definitions
 The java.base module contains a copy of the Checker Framework qualifiers.
 To update that copy:
 
-(cd $CHECKERFRAMEWORK && rm -rf checker-qual/build/libs && ./gradlew :checker-qual:sourcesJar)
-cp -pf $CHECKERFRAMEWORK/checker-qual/build/libs/checker-qual-*-source.jar checker-qual.jar
+(cd $CHECKERFRAMEWORK && rm -rf checker-qual/build/libs && ./gradlew :checker-qual:sourcesJar) && \
+cp -pf $CHECKERFRAMEWORK/checker-qual/build/libs/checker-qual-*-source.jar checker-qual.jar && \
 (cd src/java.base/share/classes && rm -rf org/checkerframework && \
   unzip ../../../../checker-qual.jar -x 'META-INF*' && \
   rm -f org/checkerframework/checker/signedness/SignednessUtilExtra.java && \
-  chmod -R u+w org/checkerframework)
+  chmod -R u+w org/checkerframework) && \
 jar tf checker-qual.jar | grep '\.java$' | sed 's/\/[^/]*\.java/;/' | sed 's/\//./g' | sed 's/^/    exports /' | sort | uniq
 
 Copy the exports lines that were printed by the last command to
diff --git a/checker-qual.jar b/checker-qual.jar
diff --git a/src/java.base/share/classes/java/lang/Class.java b/src/java.base/share/classes/java/lang/Class.java
@@ -825,7 +825,8 @@ public boolean isSynthetic(@GuardSatisfied Class<T> this) {
      * @return  the name of the class or interface
      *          represented by this object.
      */
-    @CFComment("interning: In the Oracle JDK, the result of getName is interned")
+    @CFComment({"interning: In the Oracle JDK, the result of getName is interned",
+            "signature: For a non-array non-primitive type, returns @BinaryName"})
     @Pure
     public @ClassGetName @Interned String getName() {
         String name = this.name;
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/AnnotationDesc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/AnnotationDesc.java
@@ -40,7 +40,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"nullness", "value"})
+@AnnotatedFor({"nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface AnnotationDesc {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/ClassDoc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/ClassDoc.java
@@ -49,7 +49,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"lock", "nullness", "value"})
+@AnnotatedFor({"lock", "nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface ClassDoc extends ProgramElementDoc, Type {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/Doc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/Doc.java
@@ -47,7 +47,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"lock", "nullness", "value"})
+@AnnotatedFor({"lock", "nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface Doc extends Comparable<Object> {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/ExecutableMemberDoc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/ExecutableMemberDoc.java
@@ -39,7 +39,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"nullness", "value"})
+@AnnotatedFor({"nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface ExecutableMemberDoc extends MemberDoc {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/FieldDoc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/FieldDoc.java
@@ -42,7 +42,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"lock", "nullness", "value"})
+@AnnotatedFor({"lock", "nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface FieldDoc extends MemberDoc {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/MemberDoc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/MemberDoc.java
@@ -46,7 +46,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"lock", "nullness", "value"})
+@AnnotatedFor({"lock", "nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface MemberDoc extends ProgramElementDoc {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/MethodDoc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/MethodDoc.java
@@ -39,7 +39,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"nullness", "value"})
+@AnnotatedFor({"nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface MethodDoc extends ExecutableMemberDoc {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/ParamTag.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/ParamTag.java
@@ -41,7 +41,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"nullness", "value"})
+@AnnotatedFor({"nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface ParamTag extends Tag {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/Parameter.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/Parameter.java
@@ -25,6 +25,9 @@
 
 package com.sun.javadoc;
 
+import org.checkerframework.checker.signature.qual.FqBinaryName;
+import org.checkerframework.framework.qual.AnnotatedFor;
+
 /**
  * Parameter information.
  * This includes a parameter type and parameter name.
@@ -36,6 +39,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
+@AnnotatedFor("signature")
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface Parameter {
@@ -65,7 +69,7 @@ public interface Parameter {
      *
      * @return a complete string representation of the type.
      */
-    String typeName();
+    @FqBinaryName String typeName();
 
     /**
      * Returns a string representation of the parameter.
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/ProgramElementDoc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/ProgramElementDoc.java
@@ -25,6 +25,7 @@
 
 package com.sun.javadoc;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.checkerframework.dataflow.qual.Pure;
 import org.checkerframework.framework.qual.AnnotatedFor;
@@ -45,7 +46,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"lock", "nullness", "value"})
+@AnnotatedFor({"lock", "nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface ProgramElementDoc extends Doc {
@@ -77,7 +78,7 @@ public interface ProgramElementDoc extends Doc {
      *
      * @return the qualified name of the program element as a String.
      */
-    String qualifiedName();
+    @BinaryName String qualifiedName();
 
     /**
      * Get the modifier specifier integer.
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/RootDoc.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/RootDoc.java
@@ -25,6 +25,8 @@
 
 package com.sun.javadoc;
 
+import org.checkerframework.checker.signature.qual.DotSeparatedIdentifiers;
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.common.value.qual.MinLen;
 import org.checkerframework.dataflow.qual.SideEffectFree;
 import org.checkerframework.framework.qual.AnnotatedFor;
@@ -44,7 +46,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"nullness", "value"})
+@AnnotatedFor({"nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface RootDoc extends Doc, DocErrorReporter {
@@ -108,7 +110,7 @@ public interface RootDoc extends Doc, DocErrorReporter {
      * @return a PackageDoc holding the specified package, null if
      * this package is not referenced.
      */
-    PackageDoc packageNamed(String name);
+    PackageDoc packageNamed(@DotSeparatedIdentifiers String name);
 
     /**
      * Return a ClassDoc for the specified class or interface name.
@@ -120,5 +122,5 @@ public interface RootDoc extends Doc, DocErrorReporter {
      * @return a ClassDoc holding the specified class, null if
      * this class is not referenced.
      */
-    ClassDoc classNamed(String qualifiedName);
+    ClassDoc classNamed(@BinaryName String qualifiedName);
 }
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/SourcePosition.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/SourcePosition.java
@@ -43,7 +43,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"nullness", "value"})
+@AnnotatedFor({"nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface SourcePosition {
diff --git a/src/jdk.javadoc/share/classes/com/sun/javadoc/Type.java b/src/jdk.javadoc/share/classes/com/sun/javadoc/Type.java
@@ -25,6 +25,9 @@
 
 package com.sun.javadoc;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
+import org.checkerframework.checker.signature.qual.BinaryNameOrPrimitiveType;
+import org.checkerframework.checker.signature.qual.IdentifierOrPrimitiveType;
 import org.checkerframework.dataflow.qual.Pure;
 import org.checkerframework.framework.qual.AnnotatedFor;
 
@@ -44,7 +47,7 @@
  *   in the package {@code jdk.javadoc.doclet}.
  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
  */
-@AnnotatedFor({"nullness", "value"})
+@AnnotatedFor({"nullness", "signature", "value"})
 @Deprecated(since="9", forRemoval=true)
 @SuppressWarnings("removal")
 public interface Type {
@@ -65,7 +68,7 @@ public interface Type {
      * returns "{@code java.lang.String}".
      * @return qualified name of this type excluding any dimension information.
      */
-    String qualifiedTypeName();
+    @BinaryNameOrPrimitiveType String qualifiedTypeName();
 
     /**
      * Return the simple name of this type excluding any dimension information.
@@ -78,7 +81,7 @@ public interface Type {
      * @since 1.5
      * @return the simple name of this type excluding any dimension information.
      */
-    String simpleTypeName();
+    @IdentifierOrPrimitiveType String simpleTypeName();
 
     /**
      * Return the type's dimension information, as a string.
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/AbstractTypeImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/AbstractTypeImpl.java
@@ -25,7 +25,9 @@
 
 package com.sun.tools.javadoc.main;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.dataflow.qual.Pure;
+
 import com.sun.javadoc.*;
 
 import com.sun.tools.javac.code.Type;
@@ -76,7 +78,7 @@ public String name() {
         return typeName();
     }
 
-    public String qualifiedName() {
+    public @BinaryName String qualifiedName() {
         return qualifiedTypeName();
     }
 
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/ClassDocImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/ClassDocImpl.java
@@ -25,7 +25,9 @@
 
 package com.sun.tools.javadoc.main;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.dataflow.qual.Pure;
+
 import java.io.File;
 import java.io.IOException;
 import java.lang.reflect.Modifier;
@@ -372,14 +374,14 @@ public String name() {
      *  if no qualifier, just return flat name
      * </pre>
      */
-    public String qualifiedName() {
+    public @BinaryName String qualifiedName() {
         if (qualifiedName == null) {
             qualifiedName = getClassName(tsym, true);
         }
         return qualifiedName;
     }
 
-    private String qualifiedName;
+    private @BinaryName String qualifiedName;
 
     /**
      * Return unqualified name of type excluding any dimension information.
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/ConstructorDocImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/ConstructorDocImpl.java
@@ -25,7 +25,9 @@
 
 package com.sun.tools.javadoc.main;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.dataflow.qual.Pure;
+
 import com.sun.javadoc.*;
 
 import com.sun.source.util.TreePath;
@@ -89,7 +91,7 @@ public String name() {
      *
      * @return the qualified name of the member.
      */
-    public String qualifiedName() {
+    public @BinaryName String qualifiedName() {
         return sym.enclClass().getQualifiedName().toString();
     }
 
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/DocEnv.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/DocEnv.java
@@ -25,6 +25,8 @@
 
 package com.sun.tools.javadoc.main;
 
+import org.checkerframework.checker.signature.qual.ClassGetName;
+
 import java.lang.reflect.Modifier;
 import java.util.*;
 
@@ -176,7 +178,7 @@ public void setSilent(boolean silent) {
     /**
      * Look up ClassDoc by qualified name.
      */
-    public ClassDocImpl lookupClass(String name) {
+    public ClassDocImpl lookupClass(@ClassGetName String name) {
         ClassSymbol c = getClassSymbol(name);
         if (c != null) {
             return getClassDoc(c);
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/DocImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/DocImpl.java
@@ -25,7 +25,9 @@
 
 package com.sun.tools.javadoc.main;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.dataflow.qual.Pure;
+
 import java.io.DataInputStream;
 import java.io.IOException;
 import java.io.InputStream;
@@ -306,7 +308,7 @@ public String toString() {
      *
      * @return  the name
      */
-    public abstract String qualifiedName();
+    public abstract @BinaryName String qualifiedName();
 
     /**
      * Compares this Object with the specified Object for order.  Returns a
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/FieldDocImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/FieldDocImpl.java
@@ -25,7 +25,9 @@
 
 package com.sun.tools.javadoc.main;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.dataflow.qual.Pure;
+
 import com.sun.source.util.TreePath;
 import java.lang.reflect.Modifier;
 
@@ -265,14 +267,14 @@ public String name() {
 
     private String name;
 
-    public String qualifiedName() {
+    public @BinaryName String qualifiedName() {
         if (qualifiedName == null) {
             qualifiedName = sym.enclClass().getQualifiedName() + "." + name();
         }
         return qualifiedName;
     }
 
-    private String qualifiedName;
+    private @BinaryName String qualifiedName;
 
     /**
      * Return the source position of the entity, or null if
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/MethodDocImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/MethodDocImpl.java
@@ -25,7 +25,9 @@
 
 package com.sun.tools.javadoc.main;
 
+import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.dataflow.qual.Pure;
+
 import java.lang.reflect.Modifier;
 
 import com.sun.javadoc.*;
@@ -230,14 +232,14 @@ public String name() {
 
     private String name;
 
-    public String qualifiedName() {
+    public @BinaryName String qualifiedName() {
         if (qualifiedName == null) {
             qualifiedName =  sym.enclClass().getQualifiedName() + "." + sym.name;
         }
         return qualifiedName;
     }
 
-    private String qualifiedName;
+    private @BinaryName String qualifiedName;
 
     /**
      * Returns a string representation of this method.  Includes the
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/PackageDocImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/PackageDocImpl.java
diff --git a/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/RootDocImpl.java b/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/RootDocImpl.java
