Documentation improvements

typetools · May 1, 2023 · 025d4bb · 025d4bb
1 parent 1cf92f4
commit 025d4bb
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 13 deletions.
diff --git a/...in/java/org/checkerframework/checker/calledmethods/CalledMethodsAnnotatedTypeFactory.java b/...in/java/org/checkerframework/checker/calledmethods/CalledMethodsAnnotatedTypeFactory.java
@@ -79,6 +79,7 @@ public class CalledMethodsAnnotatedTypeFactory extends AccumulationAnnotatedType
  */
  public CalledMethodsAnnotatedTypeFactory(BaseTypeChecker checker) {
  super(checker, CalledMethods.class, CalledMethodsBottom.class, CalledMethodsPredicate.class);
+
  this.builderFrameworkSupports = new ArrayList<>(2);
  String[] disabledFrameworks;
  if (checker.hasOption(CalledMethodsChecker.DISABLE_BUILDER_FRAMEWORK_SUPPORTS)) {

diff --git a/...checkerframework/common/wholeprograminference/WholeProgramInferenceJavaParserStorage.java b/...checkerframework/common/wholeprograminference/WholeProgramInferenceJavaParserStorage.java
@@ -1481,7 +1481,7 @@ public AnnotatedTypeMirror getParameterTypeInitialized(
  /**
  * Adds a declaration annotation to this parameter and returns whether it was a new annotation.
  *
- * @param annotation declaration annotation to add
+ * @param annotation the declaration annotation to add
  * @param index index of the parameter
  * @return true if {@code annotation} wasn't previously stored for this parameter
  */
@@ -1553,7 +1553,7 @@ public AnnotationMirrorSet getDeclarationAnnotations() {
  * Adds a declaration annotation to this callable declaration and returns whether it was a new
  * annotation.
  *
- * @param annotation declaration annotation to add
+ * @param annotation the declaration annotation to add
  * @return true if {@code annotation} wasn't previously stored for this callable declaration
  */
  public boolean addDeclarationAnnotation(AnnotationMirror annotation) {
@@ -1580,12 +1580,17 @@ public boolean addDeclarationAnnotation(AnnotationMirror annotation) {
  }
 
  /**
- * Returns the inferred preconditions for this callable declaration.
+ * Returns the inferred preconditions for this callable declaration. The keys of the returned
+ * map use the same string formatting as the {@link
+ * org.checkerframework.framework.qual.RequiresQualifier} annotation, e.g. "#1" for the first
+ * parameter.
  *
- * @return a mapping from expression string to pairs of (inferred precondition, declared type).
- * The keys of this map use the same string formatting as the {@link
- * org.checkerframework.framework.qual.RequiresQualifier} annotation, e.g. "#1" for the
- * first parameter.
+ * <p>Although the map is immutable, the AnnotatedTypeMirrors within it can be modified, and
+ * such changes will be reflected in the receiver CallableDeclarationAnnos object.
+ *
+ * @return a mapping from Java expression string to pairs of (inferred precondition for the
+ * expression, declared type of the expression)
+ * @see #getPreconditionsForExpression
  */
  public Map<String, Pair<AnnotatedTypeMirror, AnnotatedTypeMirror>> getPreconditions() {
  if (preconditions == null) {
@@ -1596,12 +1601,17 @@ public Map<String, Pair<AnnotatedTypeMirror, AnnotatedTypeMirror>> getPreconditi
  }
 
  /**
- * Returns the inferred postconditions for this callable declaration.
+ * Returns the inferred postconditions for this callable declaration. The keys of the returned
+ * map use the same string formatting as the {@link
+ * org.checkerframework.framework.qual.EnsuresQualifier} annotation, e.g. "#1" for the first
+ * parameter.
+ *
+ * <p>Although the map is immutable, the AnnotatedTypeMirrors within it can be modified, and
+ * such changes will be reflected in the receiver CallableDeclarationAnnos object.
  *
- * @return a mapping from expression string to pairs of (inferred postcondition, declared type).
- * The keys of this map use the same string formatting as the {@link
- * org.checkerframework.framework.qual.EnsuresQualifier} annotation, e.g. "#1" for the first
- * parameter.
+ * @return a mapping from Java expression string to pairs of (inferred postcondition for the
+ * expression, declared type of the expression)
+ * @see #getPostconditionsForExpression
  */
  public Map<String, Pair<AnnotatedTypeMirror, AnnotatedTypeMirror>> getPostconditions() {
  if (postconditions == null) {
@@ -1612,7 +1622,8 @@ public Map<String, Pair<AnnotatedTypeMirror, AnnotatedTypeMirror>> getPostcondit
  }
 
  /**
- * Returns an AnnotatedTypeMirror containing the preconditions for the given expression.
+ * Returns an AnnotatedTypeMirror containing the preconditions for the given expression. Changes
+ * to the returned AnnotatedTypeMirror are reflected in this CallableDeclarationAnnos.
  *
  * @param expression a string representing a Java expression, in the same format as the argument
  * to a {@link org.checkerframework.framework.qual.RequiresQualifier} annotation
@@ -1639,6 +1650,7 @@ public AnnotatedTypeMirror getPreconditionsForExpression(
 
  /**
  * Returns an AnnotatedTypeMirror containing the postconditions for the given expression.
+ * Changes to the returned AnnotatedTypeMirror are reflected in this CallableDeclarationAnnos.
  *
  * @param expression a string representing a Java expression, in the same format as the argument
  * to a {@link org.checkerframework.framework.qual.EnsuresQualifier} annotation