From a23b92b7ae5efbad86012b0addec2bcdb939727e Mon Sep 17 00:00:00 2001 From: Michael Ernst Date: Sun, 27 Aug 2023 09:16:04 -0700 Subject: [PATCH] Use more specific terminology than "Determines if" --- .../builder/BuilderFrameworkSupport.java | 4 +-- .../checker/index/IndexUtil.java | 13 +++++++++- .../checker/interning/InterningVisitor.java | 2 +- .../MustCallConsistencyAnalyzer.java | 2 +- .../checker/signedness/SignednessShifts.java | 10 ++++---- .../checker/signedness/SignednessVisitor.java | 4 +-- .../common/reflection/ReflectionResolver.java | 2 +- .../common/value/ValueMethodIdentifier.java | 20 +++++++++------ .../common/value/util/Range.java | 14 +++++++---- .../framework/source/SourceChecker.java | 16 ++++++------ .../framework/type/AnnotatedTypeFactory.java | 12 ++++----- .../framework/type/AnnotatedTypeMirror.java | 25 +++++++++---------- .../framework/util/Heuristics.java | 3 +-- .../checkerframework/javacutil/TreeUtils.java | 4 +-- 14 files changed, 75 insertions(+), 56 deletions(-) diff --git a/checker/src/main/java/org/checkerframework/checker/calledmethods/builder/BuilderFrameworkSupport.java b/checker/src/main/java/org/checkerframework/checker/calledmethods/builder/BuilderFrameworkSupport.java index a00a76f5b91..cbbf9951ef0 100644 --- a/checker/src/main/java/org/checkerframework/checker/calledmethods/builder/BuilderFrameworkSupport.java +++ b/checker/src/main/java/org/checkerframework/checker/calledmethods/builder/BuilderFrameworkSupport.java @@ -18,7 +18,7 @@ public interface BuilderFrameworkSupport { /** - * Determines if a method is a {@code toBuilder} method on a type generated by the builder + * Returns true if a method is a {@code toBuilder} method on a type generated by the builder * framework. * * @param candidateToBuilderElement a method @@ -39,7 +39,7 @@ public interface BuilderFrameworkSupport { void handleToBuilderMethod(AnnotatedExecutableType toBuilderType); /** - * Determines if a method is a {@code build} method on a {@code Builder} type for the builder + * Returns true if a method is a {@code build} method on a {@code Builder} type for the builder * framework. * * @param candidateBuildElement a method diff --git a/checker/src/main/java/org/checkerframework/checker/index/IndexUtil.java b/checker/src/main/java/org/checkerframework/checker/index/IndexUtil.java index 7e041da4eaf..5cc17ff13ca 100644 --- a/checker/src/main/java/org/checkerframework/checker/index/IndexUtil.java +++ b/checker/src/main/java/org/checkerframework/checker/index/IndexUtil.java @@ -13,7 +13,18 @@ /** A collection of utility functions used by several Index Checker subcheckers. */ public class IndexUtil { - /** Determines whether the type is a sequence supported by this checker. */ + + /** Do not instantiate IndexUtil. */ + private IndexUtil() { + throw new Error("Do not instantiate IndexUtil."); + } + + /** + * Returns true if the type is a sequence supported by this checker. + * + * @param type a type + * @return true if the type is a sequence supported by this checker + */ public static boolean isSequenceType(TypeMirror type) { return type.getKind() == TypeKind.ARRAY || TypesUtils.isString(type); } diff --git a/checker/src/main/java/org/checkerframework/checker/interning/InterningVisitor.java b/checker/src/main/java/org/checkerframework/checker/interning/InterningVisitor.java index 006ec4f5a56..29741a47980 100644 --- a/checker/src/main/java/org/checkerframework/checker/interning/InterningVisitor.java +++ b/checker/src/main/java/org/checkerframework/checker/interning/InterningVisitor.java @@ -913,7 +913,7 @@ private boolean classIsAnnotated(AnnotatedTypeMirror type) { } /** - * Determines whether or not the given element overrides the named method in the named class. + * Returns true if the given element overrides the named method in the named class. * * @param e an element for a method * @param clazz the class diff --git a/checker/src/main/java/org/checkerframework/checker/resourceleak/MustCallConsistencyAnalyzer.java b/checker/src/main/java/org/checkerframework/checker/resourceleak/MustCallConsistencyAnalyzer.java index a8826762ad8..c8619f5ee3d 100644 --- a/checker/src/main/java/org/checkerframework/checker/resourceleak/MustCallConsistencyAnalyzer.java +++ b/checker/src/main/java/org/checkerframework/checker/resourceleak/MustCallConsistencyAnalyzer.java @@ -842,7 +842,7 @@ private void updateObligationsWithInvocationResult(Set obligations, } /** - * Determines if the result of the given method or constructor invocation node should be tracked + * Returns true if the result of the given method or constructor invocation node should be tracked * in {@code obligations}. In some cases, there is no need to track the result because the * must-call obligations are already satisfied in some other way or there cannot possibly be * must-call obligations because of the structure of the code. diff --git a/checker/src/main/java/org/checkerframework/checker/signedness/SignednessShifts.java b/checker/src/main/java/org/checkerframework/checker/signedness/SignednessShifts.java index a04916c54a4..19c71d82f63 100644 --- a/checker/src/main/java/org/checkerframework/checker/signedness/SignednessShifts.java +++ b/checker/src/main/java/org/checkerframework/checker/signedness/SignednessShifts.java @@ -211,7 +211,7 @@ private static boolean castIgnoresMSB( } /** - * Determines if a right shift operation, {@code >>} or {@code >>>}, is masked with a masking + * Returns true if a right shift operation, {@code >>} or {@code >>>}, is masked with a masking * operation of the form {@code shiftExpr & maskLit} or {@code shiftExpr | maskLit} such that the * mask renders the shift signedness ({@code >>} vs {@code >>>}) irrelevant by destroying the bits * duplicated into the shift result. For example, the following pairs of right shifts on {@code @@ -263,10 +263,10 @@ private static boolean castIgnoresMSB( } /** - * Determines if a right shift operation, {@code >>} or {@code >>>}, is type casted such that the - * cast renders the shift signedness ({@code >>} vs {@code >>>}) irrelevant by discarding the bits - * duplicated into the shift result. For example, the following pair of right shifts on {@code - * short s} both produce the same results under any input, because of type casting: + * Returns true if a right shift operation, {@code >>} or {@code >>>}, is type casted such that + * the cast renders the shift signedness ({@code >>} vs {@code >>>}) irrelevant by discarding the + * bits duplicated into the shift result. For example, the following pair of right shifts on + * {@code short s} both produce the same results under any input, because of type casting: * *

{@code (byte)(s >> 8) == (byte)(b >>> 8);} * diff --git a/checker/src/main/java/org/checkerframework/checker/signedness/SignednessVisitor.java b/checker/src/main/java/org/checkerframework/checker/signedness/SignednessVisitor.java index ffe898e172d..0a2db385340 100644 --- a/checker/src/main/java/org/checkerframework/checker/signedness/SignednessVisitor.java +++ b/checker/src/main/java/org/checkerframework/checker/signedness/SignednessVisitor.java @@ -34,7 +34,7 @@ public SignednessVisitor(BaseTypeChecker checker) { } /** - * Determines if an annotated type is annotated as {@link Unsigned} or {@link PolySigned} + * Returns true if an annotated type is annotated as {@link Unsigned} or {@link PolySigned} * * @param type the annotated type to be checked * @return true if the annotated type is annotated as {@link Unsigned} or {@link PolySigned} @@ -44,7 +44,7 @@ private boolean hasUnsignedAnnotation(AnnotatedTypeMirror type) { } /** - * Determines if an annotated type is annotated as {@link Signed} or {@link PolySigned} + * Returns true if an annotated type is annotated as {@link Signed} or {@link PolySigned} * * @param type the annotated type to be checked * @return true if the annotated type is annotated as {@link Signed} or {@link PolySigned} diff --git a/framework/src/main/java/org/checkerframework/common/reflection/ReflectionResolver.java b/framework/src/main/java/org/checkerframework/common/reflection/ReflectionResolver.java index 1de039802c9..cd333be6d05 100644 --- a/framework/src/main/java/org/checkerframework/common/reflection/ReflectionResolver.java +++ b/framework/src/main/java/org/checkerframework/common/reflection/ReflectionResolver.java @@ -24,7 +24,7 @@ public interface ReflectionResolver { public static final List INIT_LIST = Collections.singletonList(INIT); /** - * Determines whether the given tree represents a reflective method or constructor call. + * Returns true if the given tree represents a reflective method or constructor call. * * @return {@code true} iff tree is a reflective method invocation, {@code false} otherwise */ diff --git a/framework/src/main/java/org/checkerframework/common/value/ValueMethodIdentifier.java b/framework/src/main/java/org/checkerframework/common/value/ValueMethodIdentifier.java index 37a5c6d29d5..0338c2362cb 100644 --- a/framework/src/main/java/org/checkerframework/common/value/ValueMethodIdentifier.java +++ b/framework/src/main/java/org/checkerframework/common/value/ValueMethodIdentifier.java @@ -68,13 +68,19 @@ public boolean isMathMax(Tree methodTree, ProcessingEnvironment processingEnv) { return TreeUtils.isMethodInvocation(methodTree, mathMaxMethods, processingEnv); } - /** Determines whether a tree is an invocation of the {@code String.length()} method. */ + /** + * Returns true if a tree is an invocation of the {@code String.length()} method. + * + * @param tree a tree + * @param processingEnv the processing environment + * @return true if a tree is an invocation of the {@code String.length()} method + */ public boolean isStringLengthInvocation(Tree tree, ProcessingEnvironment processingEnv) { return TreeUtils.isMethodInvocation(tree, lengthMethod, processingEnv); } /** - * Determines whether a tree is an invocation of the {@code Array.getLength()} method. + * Returns true if a tree is an invocation of the {@code Array.getLength()} method. * * @param tree tree to check * @param processingEnv the processing environment @@ -85,7 +91,7 @@ public boolean isArrayGetLengthInvocation(Tree tree, ProcessingEnvironment proce } /** - * Determines whether a method is the {@code String.length()} method. + * Returns true if a method is the {@code String.length()} method. * * @param method the element to check * @return true iff the argument methid is {@code String.length()} method @@ -96,7 +102,7 @@ public boolean isStringLengthMethod(ExecutableElement method) { } /** - * Determines whether a method is the {@code Array.getLength()} method. + * Returns true if a method is the {@code Array.getLength()} method. * * @param method the element to check * @return true iff the argument method is {@code Array.getLength()} method @@ -107,7 +113,7 @@ public boolean isArrayGetLengthMethod(ExecutableElement method) { } /** - * Determines whether a method is the {@code String.startsWith(String)} method. + * Returns true if a method is the {@code String.startsWith(String)} method. * * @param method the element to check * @return true iff the argument method is {@code String.startsWith(String)} method @@ -118,7 +124,7 @@ public boolean isStartsWithMethod(ExecutableElement method) { } /** - * Determines whether a method is the {@code String.endsWith(String)} method. + * Returns true if a method is the {@code String.endsWith(String)} method. * * @param method a method * @return true if the method is {@code String.endsWith(String)} @@ -129,7 +135,7 @@ public boolean isEndsWithMethod(ExecutableElement method) { } /** - * Determines whether a tree is an invocation of the {@code Arrays.copyOf()} method. + * Returns true if a tree is an invocation of the {@code Arrays.copyOf()} method. * * @param tree tree to check * @param processingEnv the processing environment diff --git a/framework/src/main/java/org/checkerframework/common/value/util/Range.java b/framework/src/main/java/org/checkerframework/common/value/util/Range.java index c040f8a776e..a55dc3daf47 100644 --- a/framework/src/main/java/org/checkerframework/common/value/util/Range.java +++ b/framework/src/main/java/org/checkerframework/common/value/util/Range.java @@ -1191,7 +1191,7 @@ public Range refineNotEqualTo(Range right) { } /** - * Determines if the range is wider than a given value, i.e., if the number of possible values + * Returns true if the range is wider than a given value, i.e., if the number of possible values * enclosed by this range is more than the given value. * * @param value the value to compare with @@ -1212,13 +1212,17 @@ public boolean isWiderThan(long value) { } } - /** Determines if this range represents a constant value. */ + /** + * Returns true if this range represents a constant value. + * + * @return true if this range represents a constant value + */ public boolean isConstant() { return from == to; } /** - * Determines if this range is completely contained in the range specified by the given lower + * Returns true if this range is completely contained in the range specified by the given lower * bound inclusive and upper bound inclusive. * * @param lb lower bound for the range that might contain this one @@ -1231,7 +1235,7 @@ public boolean isWithin(long lb, long ub) { } /** - * Determines if this range is contained inclusively between Long.MIN_VALUE/2 and + * Returns true if this range is contained inclusively between Long.MIN_VALUE/2 and * Long.MAX_VALUE/2. Note: Long.MIN_VALUE/2 != -Long.MAX_VALUE/2 */ private boolean isWithinHalfLong() { @@ -1239,7 +1243,7 @@ private boolean isWithinHalfLong() { } /** - * Determines if this range is completely contained in the scope of the Integer type. + * Returns true if this range is completely contained in the scope of the Integer type. * * @return true if the range is contained within the Integer range inclusive */ diff --git a/framework/src/main/java/org/checkerframework/framework/source/SourceChecker.java b/framework/src/main/java/org/checkerframework/framework/source/SourceChecker.java index 96e8d1a0b8f..bf3b920be85 100644 --- a/framework/src/main/java/org/checkerframework/framework/source/SourceChecker.java +++ b/framework/src/main/java/org/checkerframework/framework/source/SourceChecker.java @@ -2090,8 +2090,8 @@ private boolean shouldSuppressWarnings(@Nullable Object src, String errKey) { } /** - * Determines whether all the warnings pertaining to a given tree should be suppressed. Returns - * true if the tree is within the scope of a @SuppressWarnings annotation, one of whose values + * Returns true if all the warnings pertaining to a given tree should be suppressed. Returns true + * if the tree is within the scope of a @SuppressWarnings annotation, one of whose values * suppresses the checker's warning. Also, returns true if the {@code errKey} matches a string in * {@code -AsuppressWarnings}. * @@ -2123,9 +2123,9 @@ public boolean shouldSuppressWarnings(Tree tree, String errKey) { } /** - * Determines whether all the warnings pertaining to a given tree path should be suppressed. - * Returns true if the path is within the scope of a @SuppressWarnings annotation, one of whose - * values suppresses the checker's warning. + * Returns true if all the warnings pertaining to a given tree path should be suppressed. Returns + * true if the path is within the scope of a @SuppressWarnings annotation, one of whose values + * suppresses the checker's warning. * * @param path the TreePath that might be a source of, or related to, a warning * @param errKey the error key the checker is emitting @@ -2219,7 +2219,7 @@ public boolean useConservativeDefault(String kindOfCode) { protected final Set elementsWithSuppressedWarnings = new HashSet<>(); /** - * Determines whether all the warnings pertaining to a given element should be suppressed. Returns + * Returns true if all the warnings pertaining to a given element should be suppressed. Returns * true if the element is within the scope of a @SuppressWarnings annotation, one of whose values * suppresses all the checker's warnings. * @@ -2256,8 +2256,8 @@ public boolean shouldSuppressWarnings(@Nullable Element elt, String errKey) { } /** - * Determines whether an error (whose message key is {@code messageKey}) should be suppressed. It - * is suppressed if any of the given SuppressWarnings strings suppresses it. + * Returns true if an error (whose message key is {@code messageKey}) should be suppressed. It is + * suppressed if any of the given SuppressWarnings strings suppresses it. * *

A SuppressWarnings string may be of the following pattern: * diff --git a/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeFactory.java b/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeFactory.java index 0f5ab85ebfb..d5e1dbd8c00 100644 --- a/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeFactory.java +++ b/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeFactory.java @@ -3306,9 +3306,9 @@ public final AnnotatedExecutableType fromElement(ExecutableElement elt) { // ********************************************************************** /** - * Determines whether the given annotation is a part of the type system under which this type - * factory operates. Null is never a supported qualifier; the parameter is nullable to allow the - * result of canonicalAnnotation to be passed in directly. + * Returns true if the given annotation is a part of the type system under which this type factory + * operates. Null is never a supported qualifier; the parameter is nullable to allow the result of + * canonicalAnnotation to be passed in directly. * * @param a any annotation * @return true if that annotation is part of the type system under which this type factory @@ -3323,7 +3323,7 @@ public boolean isSupportedQualifier(@Nullable AnnotationMirror a) { } /** - * Determines whether the given class is a part of the type system under which this type factory + * Returns true if the given class is a part of the type system under which this type factory * operates. * * @param clazz annotation class @@ -3335,8 +3335,8 @@ public boolean isSupportedQualifier(Class clazz) { } /** - * Determines whether the given class name is a part of the type system under which this type - * factory operates. + * Returns true if the given class name is a part of the type system under which this type factory + * operates. * * @param className fully-qualified annotation class name * @return true if that class name is a type qualifier in the type system under which this type diff --git a/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeMirror.java b/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeMirror.java index 1a384e485d8..9ac8dc08752 100644 --- a/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeMirror.java +++ b/framework/src/main/java/org/checkerframework/framework/type/AnnotatedTypeMirror.java @@ -553,10 +553,10 @@ public boolean hasEffectiveAnnotation(AnnotationMirror a) { } /** - * Determines whether this type contains the given annotation explicitly written at declaration. - * This method considers the annotation's values. If the type is {@code @A("s") @B(3) Object}, a - * call with {@code @A("t")} or {@code @A} will return false, whereas a call with {@code @B(3)} - * will return true. + * Returns true if this type contains the given annotation explicitly written at declaration. This + * method considers the annotation's values. If the type is {@code @A("s") @B(3) Object}, a call + * with {@code @A("t")} or {@code @A} will return false, whereas a call with {@code @B(3)} will + * return true. * *

In contrast to {@link #hasExplicitAnnotationRelaxed(AnnotationMirror)} this method also * compares annotation values. @@ -608,7 +608,7 @@ public boolean hasExplicitAnnotationRelaxed(AnnotationMirror a) { } /** - * Determines whether this type contains an explicitly written annotation with the same annotation + * Returns true if this type contains an explicitly written annotation with the same annotation * type as a particular annotation. This method does not consider an annotation's values. * *

See the documentation for {@link #getExplicitAnnotations()} for details on which explicit @@ -2616,10 +2616,9 @@ protected final AnnotationMirrorSet getAnnotationsField() { } /** - * Determines whether this type contains the given annotation. This method considers the - * annotation's values. If the type is {@code @A("s") @B(3) Object}, then a call with - * {@code @A("t")} or {@code @A} will return false, whereas a call with {@code @B(3)} will return - * true. + * Returns true if this type contains the given annotation. This method considers the annotation's + * values. If the type is {@code @A("s") @B(3) Object}, then a call with {@code @A("t")} or + * {@code @A} will return false, whereas a call with {@code @B(3)} will return true. * *

In contrast to {@link #hasPrimaryAnnotationRelaxed(AnnotationMirror)} this method also * compares annotation values. @@ -2635,8 +2634,8 @@ public boolean hasAnnotation(AnnotationMirror a) { } /** - * Determines whether this type contains an annotation with the same annotation type as a - * particular annotation. This method does not consider an annotation's values. + * Returns true if this type contains an annotation with the same annotation type as a particular + * annotation. This method does not consider an annotation's values. * * @param a the class of annotation to check for * @return true iff the type contains an annotation with the same type as the annotation given by @@ -2663,8 +2662,8 @@ public boolean hasAnnotationInHierarchy(AnnotationMirror p) { } /** - * Determines whether this type contains an annotation with the same annotation type as a - * particular annotation. This method does not consider an annotation's values. If the type is + * Returns true if this type contains an annotation with the same annotation type as a particular + * annotation. This method does not consider an annotation's values. If the type is * {@code @A("s") @B(3) Object}, then a call with {@code @A("t")}, {@code @A}, or {@code @B} will * return true. * diff --git a/framework/src/main/java/org/checkerframework/framework/util/Heuristics.java b/framework/src/main/java/org/checkerframework/framework/util/Heuristics.java index ed0d573798c..61cd8db0a86 100644 --- a/framework/src/main/java/org/checkerframework/framework/util/Heuristics.java +++ b/framework/src/main/java/org/checkerframework/framework/util/Heuristics.java @@ -22,8 +22,7 @@ public class Heuristics { /** - * Determines whether a tree has a particular set of direct parents, ignoring blocks and - * parentheses. + * Returns true if a tree has a particular set of direct parents, ignoring blocks and parentheses. * *

For example, to test whether an expression (specified by {@code path}) is immediately * contained by an if statement which is immediately contained in a method, one would invoke: diff --git a/javacutil/src/main/java/org/checkerframework/javacutil/TreeUtils.java b/javacutil/src/main/java/org/checkerframework/javacutil/TreeUtils.java index 5de959c433a..b9ab0acd965 100644 --- a/javacutil/src/main/java/org/checkerframework/javacutil/TreeUtils.java +++ b/javacutil/src/main/java/org/checkerframework/javacutil/TreeUtils.java @@ -1805,8 +1805,8 @@ && getFieldName(tree).equals("length")) { } /** - * Determines whether or not the given {@link MethodTree} is an anonymous constructor (the - * constructor for an anonymous class). + * Returns true if the given {@link MethodTree} is an anonymous constructor (the constructor for + * an anonymous class). * * @param method a method tree that may be an anonymous constructor * @return true if the given path points to an anonymous constructor, false if it does not