Tweak documentation

docs/CHANGELOG.md

@@ -16,7 +16,11 @@ Removed deprecated names "builder", "object.construction", and
 ### Implementation details
 
 New method annotation `@DoesNotUnrefineReceiver`.
-`AnnotatedTypeFactory` has a new method `hasDoesNotUnrefineReceiver()`.
+
+In `AnnotatedTypeFactory`:
+
+* new method `hasDoesNotUnrefineReceiver()`.
+* `isAliasedTypeAnnotation()` is now protected rather than public.
 
 ### Closed issues
 

framework/src/main/java/org/checkerframework/framework/stub/AnnotationFileParser.java

@@ -729,8 +729,7 @@ public static void parseJdkFileAsStub(
       AnnotatedTypeFactory atypeFactory,
       ProcessingEnvironment processingEnv,
       AnnotationFileAnnotations stubAnnos) {
-    Map<String, String> options = processingEnv.getOptions();
-    boolean debugAnnotationFileParser = options.containsKey("stubDebug");
+    boolean debugAnnotationFileParser = processingEnv.getOptions().containsKey("stubDebug");
     if (debugAnnotationFileParser) {
       stubDebugStatic(
           processingEnv,

framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeFactory.java

@@ -3554,7 +3554,7 @@ public AnnotationMirror canonicalAnnotation(AnnotationMirror a) {
    * @param annoClass an annotation class
    * @return true if the given annotation class is an alias for some other annotation
    */
-  public boolean isAliasedTypeAnnotation(Class<?> annoClass) {
+  protected boolean isAliasedTypeAnnotation(Class<?> annoClass) {
     return aliases.containsKey(annoClass.getCanonicalName());
   }
 

framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeReplacer.java

@@ -94,9 +94,9 @@ public Void visitWildcard(AnnotatedWildcardType from, AnnotatedTypeMirror to) {
   }
 
   /**
-   * For type variables and wildcards, the absence of a primary annotations has an implied meaning
-   * on substitution. Therefore, in these cases we remove the primary annotation and rely on the
-   * fact that the bounds are also merged into the type to.
+   * For type variables and wildcards, the absence of a primary annotation has an implied meaning on
+   * substitution. Therefore, in these cases we remove the primary annotation and rely on the fact
+   * that the bounds are also merged into the type.
    *
    * @param from a type variable or wildcard
    * @param to the destination annotated type mirror

framework/src/main/java/org/checkerframework/framework/util/defaults/Default.java

@@ -9,7 +9,7 @@
 /**
  * Represents a mapping from an Annotation to a TypeUseLocation it should be applied to during
  * defaulting. The Comparable ordering of this class first tests location then tests annotation
- * ordering (via {@link org.checkerframework.javacutil.AnnotationUtils}).
+ * ordering (via {@link AnnotationUtils}).
  *
  * <p>It also has a handy toString method that is useful for debugging.
  */

framework/src/main/java/org/checkerframework/framework/util/defaults/DefaultSet.java

@@ -4,8 +4,8 @@
 import org.plumelib.util.StringsPlume;
 
 /**
- * An ordered set of Defaults (see {@link org.checkerframework.framework.util.defaults.Default}).
- * This class provides a little syntactic sugar and a better toString over TreeSet.
+ * An ordered set of Defaults (see {@link Default}). This class provides a little syntactic sugar
+ * and a better toString over TreeSet.
  */
 @SuppressWarnings("serial")
 class DefaultSet extends TreeSet<Default> {

framework/src/main/java/org/checkerframework/framework/util/element/MethodApplier.java

@@ -20,8 +20,8 @@
 import org.plumelib.util.StringsPlume;
 
 /**
- * Adds annotations from element to the return type, formal parameter types, type parameters, and
- * throws clauses of the AnnotatedExecutableType type.
+ * Adds annotations from an element to the return type, formal parameter types, type parameters, and
+ * throws clauses of an AnnotatedExecutableType type.
  */
 public class MethodApplier extends TargetedElementAnnotationApplier {
 
@@ -121,8 +121,8 @@ protected boolean isAccepted() {
   }
 
   /**
-   * Sets the method's element, annotates its return type, parameters, type parameters, and throws
-   * annotations.
+   * Sets the method's element, and annotates its return type, parameters, type parameters, and
+   * throws clauses.
    */
   @Override
   public void extractAndApply() throws UnexpectedAnnotationLocationException {
@@ -221,8 +221,10 @@ private void applyThrowsAnnotations(List<Attribute.TypeCompound> annos)
   }
 
   /**
-   * If the return type is a use of a type variable first apply the bound annotations from the type
-   * variables declaration.
+   * If the return type is a use of a type variable, first apply the bound annotations from the type
+   * variable's declaration.
+   *
+   * @throws UnexpectedAnnotationLocationException if a location is invalid
    */
   private void applyTypeVarUseOnReturnType() throws UnexpectedAnnotationLocationException {
     new TypeVarUseApplier(methodType.getReturnType(), methodSymbol, typeFactory).extractAndApply();

framework/src/main/java/org/checkerframework/framework/util/element/TargetedElementAnnotationApplier.java

@@ -29,11 +29,15 @@
  */
 abstract class TargetedElementAnnotationApplier {
   /**
-   * Three annotation types that may be encountered when calling getRawTypeAttributes. see sift().
+   * Three annotation groups that may be encountered when calling getRawTypeAttributes. See {@link
+   * #sift}.
    */
-  static enum TargetClass {
+  protected static enum TargetClass {
+    /** The annotation that should be applied to the current object. */
     TARGETED,
+    /** The annotation is valid but we will ignore it. */
     VALID,
+    /** The annotation is neither targeted nor valid. */
     INVALID
   }
 
@@ -48,7 +52,7 @@ static enum TargetClass {
    * annotations that have these target types will be passed to handleTargeted.
    *
    * @return the TargetTypes that identify annotations we wish to apply with this object. Any
-   *     annotations that have these target types will be passed to handleTargeted
+   *     annotations that have these target types will be passed to handleTargeted.
    */
   protected abstract TargetType[] annotatedTargets();