Add comments (#5655)

docs/manual/Makefile

@@ -111,6 +111,7 @@ endif
 clean:
 	@\rm -f *.aux *.blg *.dvi *.haux *.htoc *.idx *.ilg *.ind *.log *.out *.pdf *.ps *.toc manual.image.tex
 
+very-clean: very_clean
 very_clean: clean
 	@\rm -f manual.html CFLogo.png manual001.png favicon-checkerframework.png *.svg
 

framework/src/main/java/org/checkerframework/common/basetype/BaseTypeVisitor.java

@@ -2454,7 +2454,6 @@ public Void visitTypeCast(TypeCastTree tree, Void p) {
           intersection, ((IntersectionTypeTree) tree.getType()).getBounds());
     }
     return super.visitTypeCast(tree, p);
-    // return scan(tree.getExpression(), p);
   }
 
   @Override

framework/src/main/java/org/checkerframework/common/value/ValueAnnotatedTypeFactory.java

@@ -733,6 +733,7 @@ public Void visitNewArray(NewArrayTree tree, AnnotatedTypeMirror mirror) {
           }
         }
         if (numberVals.isEmpty()) {
+          // Every value in the list is a Character.
           return createCharAnnotation(characterVals);
         }
         return createNumberAnnotationMirror(new ArrayList<>(numberVals));
@@ -970,7 +971,8 @@ public AnnotationMirror createDoubleAnnotation(List<Double> values) {
   /**
    * Returns an annotation that represents the given set of values.
    *
-   * @param values a homogeneous list: every element of it has the same class
+   * @param values a homogeneous list: every element of it has the same class. This method does not
+   *     modify or store it.
    * @return an annotation that represents the given set of values
    */
   public AnnotationMirror createNumberAnnotationMirror(List<Number> values) {

framework/src/main/java/org/checkerframework/common/value/ValueCheckerUtils.java

@@ -113,14 +113,17 @@ private static <T> T convertLongToType(long value, Class<T> expectedType) {
   }
 
   /**
-   * Get all possible values from the given type and cast them into a boxed primitive type.
+   * Get all possible values from the given type and cast them into a boxed primitive type. Returns
+   * null if the list would have length greater than {@link ValueAnnotatedTypeFactory#MAX_VALUES}.
    *
    * <p>{@code expectedType} must be a boxed type, not a primitive type, because primitive types
    * cannot be stored in a list.
    *
+   * @param <T> the type of the values to obtain
    * @param range the given range
    * @param expectedType the expected type
-   * @return a list of all the values in the range
+   * @return a list of all the values in the range, or null if there would be more than {@link
+   *     ValueAnnotatedTypeFactory#MAX_VALUES}
    */
   public static <T> List<T> getValuesFromRange(Range range, Class<T> expectedType) {
     if (range == null || range.isWiderThan(ValueAnnotatedTypeFactory.MAX_VALUES)) {
@@ -198,6 +201,15 @@ private static List<?> convertStringVal(
     return strings;
   }
 
+  /**
+   * Convert a list of longs to a given type
+   *
+   * @param longs the integral values to convert
+   * @param newClass determines the type of the result
+   * @param newType the type to which to cast, if newClass is numeric
+   * @return the {@code value} of a {@code @IntVal} annotation, as a {@code List<Integer>} or a
+   *     {@code List<char[]>}
+   */
   private static List<?> convertIntVal(List<Long> longs, Class<?> newClass, TypeMirror newType) {
     if (longs == null) {
       return null;
@@ -208,7 +220,7 @@ private static List<?> convertIntVal(List<Long> longs, Class<?> newClass, TypeMi
       return CollectionsPlume.mapList((Long l) -> (char) l.longValue(), longs);
     } else if (newClass == Boolean.class) {
       throw new UnsupportedOperationException(
-          "ValueAnnotatedTypeFactory: can't convert int to boolean");
+          "ValueAnnotatedTypeFactory: can't convert integral type to boolean");
     }
     return NumberUtils.castNumbers(newType, longs);
   }

framework/src/main/java/org/checkerframework/common/value/ValueTreeAnnotator.java

@@ -121,7 +121,7 @@ public Void visitNewArray(NewArrayTree tree, AnnotatedTypeMirror type) {
    *
    * @param dimensions a list of ExpressionTrees where each ExpressionTree is a specifier of the
    *     size of that dimension
-   * @param type the AnnotatedTypeMirror of the array
+   * @param type the AnnotatedTypeMirror of the array, which is side-effected by this method
    */
   private void handleDimensions(
       List<? extends ExpressionTree> dimensions, AnnotatedTypeMirror.AnnotatedArrayType type) {
@@ -246,6 +246,7 @@ private String getCharArrayStringVal(List<? extends ExpressionTree> initializers
     return null;
   }
 
+  // Side-effects the `atm` formal parameter.
   @Override
   public Void visitTypeCast(TypeCastTree tree, AnnotatedTypeMirror atm) {
     if (handledByValueChecker(atm)) {
@@ -289,8 +290,13 @@ public Void visitTypeCast(TypeCastTree tree, AnnotatedTypeMirror atm) {
   }
 
   /**
-   * Get the "value" field of the given annotation, casted to the given type. Empty list means no
-   * value is possible (dead code). Null means no information is known -- any value is possible.
+   * Get the "value" field of the annotation on {@code type}, casted to the given type. Empty list
+   * means no value is possible (dead code). Null means no information is known -- any value is
+   * possible.
+   *
+   * @param type the type with a Value Checker annotation
+   * @param castTo the type to cast to
+   * @return the Value Checker annotation's value, casted to the given type
    */
   private List<?> getValues(AnnotatedTypeMirror type, TypeMirror castTo) {
     AnnotationMirror anno = type.getAnnotationInHierarchy(atypeFactory.UNKNOWNVAL);

framework/src/main/java/org/checkerframework/common/value/util/NumberUtils.java

@@ -9,7 +9,18 @@
 /** Utility routines for manipulating numbers. */
 public class NumberUtils {
 
-  /** Converts a {@code List<A>} to a {@code List<B>}, where A and B are numeric types. */
+  /** Do not instantiate. */
+  private NumberUtils() {
+    throw new Error("Do not instantiate");
+  }
+
+  /**
+   * Converts a {@code List<A>} to a {@code List<B>}, where A and B are numeric types.
+   *
+   * @param type the type to cast to
+   * @param numbers the numbers to cast to the given type
+   * @return a list of numbers of the given type
+   */
   public static List<? extends Number> castNumbers(
       TypeMirror type, List<? extends Number> numbers) {
     if (numbers == null) {

framework/src/main/java/org/checkerframework/common/value/util/Range.java

@@ -340,6 +340,8 @@ public Range intRange() {
    * <p>If {@link #ignoreOverflow} is false and the bounds of this range are not representable as
    * 16-bit integers, convert the bounds to Short type in accordance with Java twos-complement
    * overflow rules, e.g., Short.MAX_VALUE + 1 is converted to Short.MIN_VALUE.
+   *
+   * @return this range, converted to a 16-bit short range
    */
   public Range shortRange() {
     if (this.isNothing()) {
@@ -389,7 +391,7 @@ public Range charRange() {
   }
 
   /**
-   * Converts this range to a 8-bit byte range.
+   * Converts this range to an 8-bit byte range.
    *
    * <p>If {@link #ignoreOverflow} is true and one of the bounds is outside the Byte range, then
    * that bound is set to the bound of the Byte range.
@@ -400,6 +402,8 @@ public Range charRange() {
    * <p>If {@link #ignoreOverflow} is false and the bounds of this range are not representable as
    * 8-bit integers, convert the bounds to Byte type in accordance with Java twos-complement
    * overflow rules, e.g., Byte.MAX_VALUE + 1 is converted to Byte.MIN_VALUE.
+   *
+   * @return this range, converted to an 8-bit byte range
    */
   public Range byteRange() {
     if (this.isNothing()) {