[KeepAnno] Fix all javadoc warnings
Bug: b/248408342
Change-Id: I1cba06b71ad0befaa509699d8fd4f8540b3ec447
diff --git a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepBinding.java b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepBinding.java
index 9657a22..0e79f51 100644
--- a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepBinding.java
+++ b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepBinding.java
@@ -31,7 +31,11 @@
@Retention(RetentionPolicy.CLASS)
public @interface KeepBinding {
- /** Name with which other bindings, conditions or targets can reference the bound item pattern. */
+ /**
+ * Name with which other bindings, conditions or targets can reference the bound item pattern.
+ *
+ * @return Name of the binding.
+ */
String bindingName();
/**
@@ -47,6 +51,8 @@
*
* <p>If unspecified the default for an item with no member patterns is ONLY_CLASS and if it does
* have member patterns the default is ONLY_MEMBERS
+ *
+ * @return The kind for this pattern.
*/
KeepItemKind kind() default KeepItemKind.DEFAULT;
@@ -67,6 +73,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class.
+ *
+ * @return The name of the binding that defines the class.
*/
String classFromBinding() default "";
@@ -81,6 +89,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class name.
+ *
+ * @return The qualified class name that defines the class.
*/
String className() default "";
@@ -95,6 +105,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class name.
+ *
+ * @return The class-constant that defines the class.
*/
Class<?> classConstant() default Object.class;
@@ -113,6 +125,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The qualified class name that defines what instance-of the class must be.
*/
String instanceOfClassName() default "";
@@ -134,6 +148,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The qualified class name that defines what instance-of the class must be.
*/
String instanceOfClassNameExclusive() default "";
@@ -152,6 +168,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what instance-of the class must be.
*/
Class<?> instanceOfClassConstant() default Object.class;
@@ -173,6 +191,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what instance-of the class must be.
*/
Class<?> instanceOfClassConstantExclusive() default Object.class;
@@ -196,6 +216,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class name that defines what the class must extend.
*/
String extendsClassName() default "";
@@ -219,6 +241,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what the class must extend.
*/
Class<?> extendsClassConstant() default Object.class;
@@ -227,6 +251,8 @@
*
* <p>Mutually exclusive with all field and method properties as use restricts the match to both
* types of members.
+ *
+ * @return The access flags constraints that must be met.
*/
MemberAccessFlags[] memberAccess() default {};
@@ -237,6 +263,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* method-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
MethodAccessFlags[] methodAccess() default {};
@@ -247,6 +275,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any method
* name.
+ *
+ * @return The exact method name of the method.
*/
String methodName() default "";
@@ -257,6 +287,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any return
* type.
+ *
+ * @return The qualified type name of the method return type.
*/
String methodReturnType() default "";
@@ -267,6 +299,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* parameters.
+ *
+ * @return The list of qualified type names of the method parameters.
*/
String[] methodParameters() default {"<default>"};
@@ -277,6 +311,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any
* field-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
FieldAccessFlags[] fieldAccess() default {};
@@ -287,6 +323,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any field
* name.
+ *
+ * @return The exact field name of the field.
*/
String fieldName() default "";
@@ -296,6 +334,8 @@
* <p>Mutually exclusive with all method properties.
*
* <p>If none, and other properties define this item as a field, the default matches any type.
+ *
+ * @return The qualified type name of the field type.
*/
String fieldType() default "";
}
diff --git a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepCondition.java b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepCondition.java
index 7777fd8..ecdb94e 100644
--- a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepCondition.java
+++ b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepCondition.java
@@ -45,6 +45,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class.
+ *
+ * @return The name of the binding that defines the class.
*/
String classFromBinding() default "";
@@ -59,6 +61,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class name.
+ *
+ * @return The qualified class name that defines the class.
*/
String className() default "";
@@ -73,6 +77,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class name.
+ *
+ * @return The class-constant that defines the class.
*/
Class<?> classConstant() default Object.class;
@@ -91,6 +97,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The qualified class name that defines what instance-of the class must be.
*/
String instanceOfClassName() default "";
@@ -112,6 +120,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The qualified class name that defines what instance-of the class must be.
*/
String instanceOfClassNameExclusive() default "";
@@ -130,6 +140,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what instance-of the class must be.
*/
Class<?> instanceOfClassConstant() default Object.class;
@@ -151,6 +163,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what instance-of the class must be.
*/
Class<?> instanceOfClassConstantExclusive() default Object.class;
@@ -174,6 +188,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class name that defines what the class must extend.
*/
String extendsClassName() default "";
@@ -197,6 +213,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what the class must extend.
*/
Class<?> extendsClassConstant() default Object.class;
@@ -205,6 +223,8 @@
*
* <p>Mutually exclusive with all other class and member pattern properties. When a member binding
* is referenced this item is defined to be that item, including its class and member patterns.
+ *
+ * @return The binding name that defines the member.
*/
String memberFromBinding() default "";
@@ -213,6 +233,8 @@
*
* <p>Mutually exclusive with all field and method properties as use restricts the match to both
* types of members.
+ *
+ * @return The access flags constraints that must be met.
*/
MemberAccessFlags[] memberAccess() default {};
@@ -223,6 +245,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* method-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
MethodAccessFlags[] methodAccess() default {};
@@ -233,6 +257,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any method
* name.
+ *
+ * @return The exact method name of the method.
*/
String methodName() default "";
@@ -243,6 +269,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any return
* type.
+ *
+ * @return The qualified type name of the method return type.
*/
String methodReturnType() default "";
@@ -253,6 +281,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* parameters.
+ *
+ * @return The list of qualified type names of the method parameters.
*/
String[] methodParameters() default {"<default>"};
@@ -263,6 +293,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any
* field-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
FieldAccessFlags[] fieldAccess() default {};
@@ -273,6 +305,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any field
* name.
+ *
+ * @return The exact field name of the field.
*/
String fieldName() default "";
@@ -282,6 +316,8 @@
* <p>Mutually exclusive with all method properties.
*
* <p>If none, and other properties define this item as a field, the default matches any type.
+ *
+ * @return The qualified type name of the field type.
*/
String fieldType() default "";
}
diff --git a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepForApi.java b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepForApi.java
index 65454fe..c204abd 100644
--- a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepForApi.java
+++ b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepForApi.java
@@ -27,13 +27,17 @@
@Retention(RetentionPolicy.CLASS)
public @interface KeepForApi {
- /** Optional description to document the reason for this annotation. */
+ /**
+ * Optional description to document the reason for this annotation.
+ *
+ * @return The descriptive message. Defaults to no description.
+ */
String description() default "";
/**
* Additional targets to be kept as part of the API surface.
*
- * <p>Defaults to no additional targets.
+ * @return List of additional target consequences. Defaults to no additional target consequences.
*/
KeepTarget[] additionalTargets() default {};
@@ -46,6 +50,8 @@
*
* <p>It is not possible to use ONLY_CLASS if annotating a member. Also, it is never valid to use
* kind ONLY_MEMBERS as the API surface must keep the class if any member is to be accessible.
+ *
+ * @return The kind for this pattern.
*/
KeepItemKind kind() default KeepItemKind.DEFAULT;
@@ -54,6 +60,8 @@
*
* <p>Mutually exclusive with all field and method properties as use restricts the match to both
* types of members.
+ *
+ * @return The access flags constraints that must be met.
*/
MemberAccessFlags[] memberAccess() default {};
@@ -64,6 +72,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* method-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
MethodAccessFlags[] methodAccess() default {};
@@ -74,6 +84,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any method
* name.
+ *
+ * @return The exact method name of the method.
*/
String methodName() default "";
@@ -84,6 +96,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any return
* type.
+ *
+ * @return The qualified type name of the method return type.
*/
String methodReturnType() default "";
@@ -94,6 +108,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* parameters.
+ *
+ * @return The list of qualified type names of the method parameters.
*/
String[] methodParameters() default {"<default>"};
@@ -104,6 +120,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any
* field-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
FieldAccessFlags[] fieldAccess() default {};
@@ -114,6 +132,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any field
* name.
+ *
+ * @return The exact field name of the field.
*/
String fieldName() default "";
@@ -123,6 +143,8 @@
* <p>Mutually exclusive with all method properties.
*
* <p>If none, and other properties define this item as a field, the default matches any type.
+ *
+ * @return The qualified type name of the field type.
*/
String fieldType() default "";
}
diff --git a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepTarget.java b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepTarget.java
index 59e7e7c..3b80210 100644
--- a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepTarget.java
+++ b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/KeepTarget.java
@@ -41,24 +41,34 @@
*
* <p>If unspecified the default for an item with no member patterns is ONLY_CLASS and if it does
* have member patterns the default is ONLY_MEMBERS
+ *
+ * @return The kind for this pattern.
*/
KeepItemKind kind() default KeepItemKind.DEFAULT;
/**
- * Define the options that do not need to be preserved for the target.
+ * Define the options that are allowed to be modified.
+ *
+ * <p>The specified options do not need to be preserved for the target.
*
* <p>Mutually exclusive with the property `disallow` also defining options.
*
* <p>If nothing is specified for options the default is "allow none" / "disallow all".
+ *
+ * @return Options allowed to be modified for the target.
*/
KeepOption[] allow() default {};
/**
- * Define the options that *must* be preserved for the target.
+ * Define the options that are not allowed to be modified.
+ *
+ * <p>The specified options *must* be preserved for the target.
*
* <p>Mutually exclusive with the property `allow` also defining options.
*
* <p>If nothing is specified for options the default is "allow none" / "disallow all".
+ *
+ * @return Options not allowed to be modified for the target.
*/
KeepOption[] disallow() default {};
@@ -79,6 +89,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class.
+ *
+ * @return The name of the binding that defines the class.
*/
String classFromBinding() default "";
@@ -93,6 +105,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class name.
+ *
+ * @return The qualified class name that defines the class.
*/
String className() default "";
@@ -107,6 +121,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class name.
+ *
+ * @return The class-constant that defines the class.
*/
Class<?> classConstant() default Object.class;
@@ -125,6 +141,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The qualified class name that defines what instance-of the class must be.
*/
String instanceOfClassName() default "";
@@ -146,6 +164,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The qualified class name that defines what instance-of the class must be.
*/
String instanceOfClassNameExclusive() default "";
@@ -164,6 +184,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what instance-of the class must be.
*/
Class<?> instanceOfClassConstant() default Object.class;
@@ -185,6 +207,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what instance-of the class must be.
*/
Class<?> instanceOfClassConstantExclusive() default Object.class;
@@ -208,6 +232,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class name that defines what the class must extend.
*/
String extendsClassName() default "";
@@ -231,6 +257,8 @@
* </ul>
*
* <p>If none are specified the default is to match any class instance.
+ *
+ * @return The class constant that defines what the class must extend.
*/
Class<?> extendsClassConstant() default Object.class;
@@ -239,6 +267,8 @@
*
* <p>Mutually exclusive with all other class and member pattern properties. When a member binding
* is referenced this item is defined to be that item, including its class and member patterns.
+ *
+ * @return The binding name that defines the member.
*/
String memberFromBinding() default "";
@@ -247,6 +277,8 @@
*
* <p>Mutually exclusive with all field and method properties as use restricts the match to both
* types of members.
+ *
+ * @return The access flags constraints that must be met.
*/
MemberAccessFlags[] memberAccess() default {};
@@ -257,6 +289,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* method-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
MethodAccessFlags[] methodAccess() default {};
@@ -267,6 +301,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any method
* name.
+ *
+ * @return The exact method name of the method.
*/
String methodName() default "";
@@ -277,6 +313,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any return
* type.
+ *
+ * @return The qualified type name of the method return type.
*/
String methodReturnType() default "";
@@ -287,6 +325,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* parameters.
+ *
+ * @return The list of qualified type names of the method parameters.
*/
String[] methodParameters() default {"<default>"};
@@ -297,6 +337,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any
* field-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
FieldAccessFlags[] fieldAccess() default {};
@@ -307,6 +349,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any field
* name.
+ *
+ * @return The exact field name of the field.
*/
String fieldName() default "";
@@ -316,6 +360,8 @@
* <p>Mutually exclusive with all method properties.
*
* <p>If none, and other properties define this item as a field, the default matches any type.
+ *
+ * @return The qualified type name of the field type.
*/
String fieldType() default "";
}
diff --git a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByNative.java b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByNative.java
index b1ad804..57e3969 100644
--- a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByNative.java
+++ b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByNative.java
@@ -32,20 +32,25 @@
@Retention(RetentionPolicy.CLASS)
public @interface UsedByNative {
- /** Optional description to document the reason for this annotation. */
+ /**
+ * Optional description to document the reason for this annotation.
+ *
+ * @return The descriptive message. Defaults to no description.
+ */
String description() default "";
/**
* Conditions that should be satisfied for the annotation to be in effect.
*
- * <p>Defaults to no conditions, thus trivially/unconditionally satisfied.
+ * @return The list of preconditions. Defaults to no conditions, thus trivially/unconditionally
+ * satisfied.
*/
KeepCondition[] preconditions() default {};
/**
* Additional targets to be kept in addition to the annotated class/members.
*
- * <p>Defaults to no additional targets.
+ * @return List of additional target consequences. Defaults to no additional target consequences.
*/
KeepTarget[] additionalTargets() default {};
@@ -61,6 +66,8 @@
* <p>When annotating a member, the default kind is {@link KeepItemKind#ONLY_MEMBERS}.
*
* <p>It is not possible to use ONLY_CLASS if annotating a member.
+ *
+ * @return The kind for this pattern.
*/
KeepItemKind kind() default KeepItemKind.DEFAULT;
@@ -69,6 +76,8 @@
*
* <p>Mutually exclusive with all field and method properties as use restricts the match to both
* types of members.
+ *
+ * @return The access flags constraints that must be met.
*/
MemberAccessFlags[] memberAccess() default {};
@@ -79,6 +88,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* method-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
MethodAccessFlags[] methodAccess() default {};
@@ -89,6 +100,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any method
* name.
+ *
+ * @return The exact method name of the method.
*/
String methodName() default "";
@@ -99,6 +112,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any return
* type.
+ *
+ * @return The qualified type name of the method return type.
*/
String methodReturnType() default "";
@@ -109,6 +124,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* parameters.
+ *
+ * @return The list of qualified type names of the method parameters.
*/
String[] methodParameters() default {"<default>"};
@@ -119,6 +136,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any
* field-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
FieldAccessFlags[] fieldAccess() default {};
@@ -129,6 +148,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any field
* name.
+ *
+ * @return The exact field name of the field.
*/
String fieldName() default "";
@@ -138,6 +159,8 @@
* <p>Mutually exclusive with all method properties.
*
* <p>If none, and other properties define this item as a field, the default matches any type.
+ *
+ * @return The qualified type name of the field type.
*/
String fieldType() default "";
}
diff --git a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByReflection.java b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByReflection.java
index 27489cb..85f00a6 100644
--- a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByReflection.java
+++ b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsedByReflection.java
@@ -32,20 +32,25 @@
@Retention(RetentionPolicy.CLASS)
public @interface UsedByReflection {
- /** Optional description to document the reason for this annotation. */
+ /**
+ * Optional description to document the reason for this annotation.
+ *
+ * @return The descriptive message. Defaults to no description.
+ */
String description() default "";
/**
* Conditions that should be satisfied for the annotation to be in effect.
*
- * <p>Defaults to no conditions, thus trivially/unconditionally satisfied.
+ * @return The list of preconditions. Defaults to no conditions, thus trivially/unconditionally
+ * satisfied.
*/
KeepCondition[] preconditions() default {};
/**
* Additional targets to be kept in addition to the annotated class/members.
*
- * <p>Defaults to no additional targets.
+ * @return List of additional target consequences. Defaults to no additional target consequences.
*/
KeepTarget[] additionalTargets() default {};
@@ -61,6 +66,8 @@
* <p>When annotating a member, the default kind is {@link KeepItemKind#ONLY_MEMBERS}.
*
* <p>It is not possible to use ONLY_CLASS if annotating a member.
+ *
+ * @return The kind for this pattern.
*/
KeepItemKind kind() default KeepItemKind.DEFAULT;
@@ -69,6 +76,8 @@
*
* <p>Mutually exclusive with all field and method properties as use restricts the match to both
* types of members.
+ *
+ * @return The access flags constraints that must be met.
*/
MemberAccessFlags[] memberAccess() default {};
@@ -79,6 +88,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* method-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
MethodAccessFlags[] methodAccess() default {};
@@ -89,6 +100,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any method
* name.
+ *
+ * @return The exact method name of the method.
*/
String methodName() default "";
@@ -99,6 +112,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any return
* type.
+ *
+ * @return The qualified type name of the method return type.
*/
String methodReturnType() default "";
@@ -109,6 +124,8 @@
*
* <p>If none, and other properties define this item as a method, the default matches any
* parameters.
+ *
+ * @return The list of qualified type names of the method parameters.
*/
String[] methodParameters() default {"<default>"};
@@ -119,6 +136,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any
* field-access flags.
+ *
+ * @return The access flags constraints that must be met.
*/
FieldAccessFlags[] fieldAccess() default {};
@@ -129,6 +148,8 @@
*
* <p>If none, and other properties define this item as a field, the default matches any field
* name.
+ *
+ * @return The exact field name of the field.
*/
String fieldName() default "";
@@ -138,6 +159,8 @@
* <p>Mutually exclusive with all method properties.
*
* <p>If none, and other properties define this item as a field, the default matches any type.
+ *
+ * @return The qualified type name of the field type.
*/
String fieldType() default "";
}
diff --git a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsesReflection.java b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsesReflection.java
index 56a215d..fd28b1a 100644
--- a/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsesReflection.java
+++ b/src/keepanno/java/com/android/tools/r8/keepanno/annotations/UsesReflection.java
@@ -63,16 +63,24 @@
@Retention(RetentionPolicy.CLASS)
public @interface UsesReflection {
- /** Optional description to document the reason for this annotation. */
+ /**
+ * Optional description to document the reason for this annotation.
+ *
+ * @return The descriptive message. Defaults to no description.
+ */
String description() default "";
- /** Consequences that must be kept if the annotation is in effect. */
+ /**
+ * Consequences that must be kept if the annotation is in effect.
+ *
+ * @return The list of target consequences.
+ */
KeepTarget[] value();
/**
* Additional preconditions for the annotation to be in effect.
*
- * <p>Defaults to no additional preconditions.
+ * @return The list of additional preconditions. Defaults to no additional preconditions.
*/
KeepCondition[] additionalPreconditions() default {};
}
diff --git a/src/test/java/com/android/tools/r8/keepanno/utils/DocPrinterBase.java b/src/test/java/com/android/tools/r8/keepanno/utils/DocPrinterBase.java
index f193da6..7a9b073 100644
--- a/src/test/java/com/android/tools/r8/keepanno/utils/DocPrinterBase.java
+++ b/src/test/java/com/android/tools/r8/keepanno/utils/DocPrinterBase.java
@@ -13,10 +13,15 @@
public abstract class DocPrinterBase<T> {
private String title = null;
+ private String returnDesc = null;
private final List<String> additionalLines = new ArrayList<>();
public abstract T self();
+ private boolean isEmptyOrJustTitle() {
+ return returnDesc == null && additionalLines.isEmpty();
+ }
+
public T clearDocLines() {
additionalLines.clear();
return self();
@@ -29,6 +34,11 @@
return self();
}
+ public T setDocReturn(String desc) {
+ returnDesc = desc;
+ return self();
+ }
+
public T addParagraph(String... lines) {
return addParagraph(Arrays.asList(lines));
}
@@ -67,11 +77,11 @@
}
public void printDoc(Consumer<String> println) {
- assert additionalLines.isEmpty() || title != null;
if (title == null) {
+ assert isEmptyOrJustTitle();
return;
}
- if (additionalLines.isEmpty()) {
+ if (isEmptyOrJustTitle()) {
println.accept("/** " + title + " */");
return;
}
@@ -83,6 +93,9 @@
}
println.accept(" * " + line);
}
+ if (returnDesc != null) {
+ println.accept(" * @return " + returnDesc);
+ }
println.accept(" */");
}
}
diff --git a/src/test/java/com/android/tools/r8/keepanno/utils/KeepItemAnnotationGenerator.java b/src/test/java/com/android/tools/r8/keepanno/utils/KeepItemAnnotationGenerator.java
index 67a5fe0..5ef1f58 100644
--- a/src/test/java/com/android/tools/r8/keepanno/utils/KeepItemAnnotationGenerator.java
+++ b/src/test/java/com/android/tools/r8/keepanno/utils/KeepItemAnnotationGenerator.java
@@ -265,6 +265,7 @@
.addMember(
new GroupMember("description")
.setDocTitle("Optional description to document the reason for this annotation.")
+ .setDocReturn("The descriptive message. Defaults to no description.")
.defaultEmptyString());
}
@@ -279,8 +280,9 @@
new GroupMember("preconditions")
.setDocTitle(
"Conditions that should be satisfied for the annotation to be in effect.")
- .addParagraph(
- "Defaults to no conditions, thus trivially/unconditionally satisfied.")
+ .setDocReturn(
+ "The list of preconditions. "
+ + "Defaults to no conditions, thus trivially/unconditionally satisfied.")
.defaultEmptyArray(KeepCondition.class));
}
@@ -289,6 +291,7 @@
.addMember(
new GroupMember("consequences")
.setDocTitle("Consequences that must be kept if the annotation is in effect.")
+ .setDocReturn("The list of target consequences.")
.requiredValueOfArrayType(KeepTarget.class));
}
@@ -297,6 +300,7 @@
.addMember(
new GroupMember("value")
.setDocTitle("Consequences that must be kept if the annotation is in effect.")
+ .setDocReturn("The list of target consequences.")
.requiredValueOfArrayType(KeepTarget.class));
}
@@ -305,7 +309,9 @@
.addMember(
new GroupMember("additionalPreconditions")
.setDocTitle("Additional preconditions for the annotation to be in effect.")
- .addParagraph("Defaults to no additional preconditions.")
+ .setDocReturn(
+ "The list of additional preconditions. "
+ + "Defaults to no additional preconditions.")
.defaultEmptyArray("KeepCondition"));
}
@@ -314,7 +320,9 @@
.addMember(
new GroupMember("additionalTargets")
.setDocTitle(docTitle)
- .addParagraph("Defaults to no additional targets.")
+ .setDocReturn(
+ "List of additional target consequences. "
+ + "Defaults to no additional target consequences.")
.defaultEmptyArray("KeepTarget"));
}
@@ -327,6 +335,7 @@
.defaultType("KeepItemKind")
.defaultValue("KeepItemKind.DEFAULT")
.setDocTitle("Specify the kind of this item pattern.")
+ .setDocReturn("The kind for this pattern.")
.addParagraph("Possible values are:")
.addUnorderedList(
KeepItemKind.ONLY_CLASS.name(),
@@ -343,15 +352,16 @@
return new Group(OPTIONS_GROUP)
.addMember(
new GroupMember("allow")
- .setDocTitle(
- "Define the "
- + OPTIONS_GROUP
- + " that do not need to be preserved for the target.")
+ .setDocTitle("Define the " + OPTIONS_GROUP + " that are allowed to be modified.")
+ .addParagraph("The specified options do not need to be preserved for the target.")
+ .setDocReturn("Options allowed to be modified for the target.")
.defaultEmptyArray("KeepOption"))
.addMember(
new GroupMember("disallow")
.setDocTitle(
- "Define the " + OPTIONS_GROUP + " that *must* be preserved for the target.")
+ "Define the " + OPTIONS_GROUP + " that are not allowed to be modified.")
+ .addParagraph("The specified options *must* be preserved for the target.")
+ .setDocReturn("Options not allowed to be modified for the target.")
.defaultEmptyArray("KeepOption"))
.addDocFooterParagraph(
"If nothing is specified for "
@@ -368,12 +378,14 @@
.setDocTitle(
"Name with which other bindings, conditions or targets "
+ "can reference the bound item pattern.")
+ .setDocReturn("Name of the binding.")
.requiredStringValue();
}
private GroupMember classFromBinding() {
return new GroupMember("classFromBinding")
.setDocTitle("Define the " + CLASS_GROUP + " pattern by reference to a binding.")
+ .setDocReturn("The name of the binding that defines the class.")
.defaultEmptyString();
}
@@ -386,6 +398,7 @@
private GroupMember className() {
return new GroupMember("className")
.setDocTitle("Define the " + CLASS_NAME_GROUP + " pattern by fully qualified class name.")
+ .setDocReturn("The qualified class name that defines the class.")
.defaultEmptyString();
}
@@ -393,6 +406,7 @@
return new GroupMember("classConstant")
.setDocTitle(
"Define the " + CLASS_NAME_GROUP + " pattern by reference to a Class constant.")
+ .setDocReturn("The class-constant that defines the class.")
.defaultObjectClass();
}
@@ -409,6 +423,7 @@
"Define the "
+ INSTANCE_OF_GROUP
+ " pattern as classes that are instances of the fully qualified class name.")
+ .setDocReturn("The qualified class name that defines what instance-of the class must be.")
.defaultEmptyString();
}
@@ -418,6 +433,7 @@
"Define the "
+ INSTANCE_OF_GROUP
+ " pattern as classes that are instances the referenced Class constant.")
+ .setDocReturn("The class constant that defines what instance-of the class must be.")
.defaultObjectClass();
}
@@ -433,6 +449,7 @@
"Define the "
+ INSTANCE_OF_GROUP
+ " pattern as classes that are instances of the fully qualified class name.")
+ .setDocReturn("The qualified class name that defines what instance-of the class must be.")
.addParagraph(getInstanceOfExclusiveDoc())
.defaultEmptyString();
}
@@ -444,6 +461,7 @@
+ INSTANCE_OF_GROUP
+ " pattern as classes that are instances the referenced Class constant.")
.addParagraph(getInstanceOfExclusiveDoc())
+ .setDocReturn("The class constant that defines what instance-of the class must be.")
.defaultObjectClass();
}
@@ -455,6 +473,7 @@
+ " pattern as classes extending the fully qualified class name.")
.addParagraph(getInstanceOfExclusiveDoc())
.addParagraph("This property is deprecated, use instanceOfClassName instead.")
+ .setDocReturn("The class name that defines what the class must extend.")
.defaultEmptyString();
}
@@ -466,6 +485,7 @@
+ " pattern as classes extending the referenced Class constant.")
.addParagraph(getInstanceOfExclusiveDoc())
.addParagraph("This property is deprecated, use instanceOfClassConstant instead.")
+ .setDocReturn("The class constant that defines what the class must extend.")
.defaultObjectClass();
}
@@ -490,6 +510,7 @@
"Mutually exclusive with all other class and member pattern properties.",
"When a member binding is referenced this item is defined to be that item,",
"including its class and member patterns.")
+ .setDocReturn("The binding name that defines the member.")
.defaultEmptyString());
}
@@ -501,6 +522,7 @@
.addParagraph(
"Mutually exclusive with all field and method properties",
"as use restricts the match to both types of members.")
+ .setDocReturn("The access flags constraints that must be met.")
.defaultEmptyArray("MemberAccessFlags"));
}
@@ -531,6 +553,7 @@
.setDocTitle("Define the method-access pattern by matching on access flags.")
.addParagraph(getMutuallyExclusiveForMethodProperties())
.addParagraph(getMethodDefaultDoc("any method-access flags"))
+ .setDocReturn("The access flags constraints that must be met.")
.defaultEmptyArray("MethodAccessFlags"));
}
@@ -541,6 +564,7 @@
.setDocTitle("Define the method-name pattern by an exact method name.")
.addParagraph(getMutuallyExclusiveForMethodProperties())
.addParagraph(getMethodDefaultDoc("any method name"))
+ .setDocReturn("The exact method name of the method.")
.defaultEmptyString());
}
@@ -552,6 +576,7 @@
"Define the method return-type pattern by a fully qualified type or 'void'.")
.addParagraph(getMutuallyExclusiveForMethodProperties())
.addParagraph(getMethodDefaultDoc("any return type"))
+ .setDocReturn("The qualified type name of the method return type.")
.defaultEmptyString());
}
@@ -563,6 +588,7 @@
"Define the method parameters pattern by a list of fully qualified types.")
.addParagraph(getMutuallyExclusiveForMethodProperties())
.addParagraph(getMethodDefaultDoc("any parameters"))
+ .setDocReturn("The list of qualified type names of the method parameters.")
.defaultType("String[]")
.defaultValue("{\"<default>\"}"));
}
@@ -574,6 +600,7 @@
.setDocTitle("Define the field-access pattern by matching on access flags.")
.addParagraph(getMutuallyExclusiveForFieldProperties())
.addParagraph(getFieldDefaultDoc("any field-access flags"))
+ .setDocReturn("The access flags constraints that must be met.")
.defaultEmptyArray("FieldAccessFlags"));
}
@@ -584,6 +611,7 @@
.setDocTitle("Define the field-name pattern by an exact field name.")
.addParagraph(getMutuallyExclusiveForFieldProperties())
.addParagraph(getFieldDefaultDoc("any field name"))
+ .setDocReturn("The exact field name of the field.")
.defaultEmptyString());
}
@@ -594,6 +622,7 @@
.setDocTitle("Define the field-type pattern by a fully qualified type.")
.addParagraph(getMutuallyExclusiveForFieldProperties())
.addParagraph(getFieldDefaultDoc("any type"))
+ .setDocReturn("The qualified type name of the field type.")
.defaultEmptyString());
}
@@ -674,12 +703,7 @@
println();
withIndent(
() -> {
- new GroupMember("bindingName")
- .setDocTitle(
- "Name with which other bindings, conditions or targets can reference the bound"
- + " item pattern.")
- .requiredValueOfType("String")
- .generate(this);
+ bindingName().generate(this);
println();
getKindGroup().generate(this);
println();
