update comments, javadoc RecordIndexingService

Author: supersaiyansubtlety

enigma/src/main/java/org/quiltmc/enigma/impl/plugin/RecordIndexingService.java

@@ -12,6 +12,34 @@
 import java.util.Set;
 import java.util.stream.Stream;
 
+/**
+ * Indexes records, finding component getters and their corresponding fields.
+ *
+ * <p> While component fields can be reliably indexed, there can be uncertainty in determining their corresponding
+ * getters. Some getters can be definitively determined, some are classified as 'probable getters'
+ * (probabilistically determined), and some cannot be determined at all.
+ *
+ * <p> {@link RecordIndexingService} provides separate methods for accessing getters that are definitive, probabilistic,
+ * or either.<br>
+ * Either:
+ * <ul>
+ *     <li> {@link #getComponentGetter(FieldEntry)}
+ *     <li> {@link #getComponentField(MethodEntry)}
+ *     <li> {@link #streamComponentMethods(ClassEntry)}
+ * </ul>
+ * Definite:
+ * <ul>
+ *     <li> {@link #getDefiniteComponentGetter(FieldEntry)}
+ *     <li> {@link #getDefiniteComponentField(MethodEntry)}
+ *     <li> {@link #streamDefiniteComponentMethods(ClassEntry)}
+ * </ul>
+ * Probable:
+ * <ul>
+ *     <li> {@link #getProbableComponentGetter(FieldEntry)}
+ *     <li> {@link #getProbableComponentField(MethodEntry)}
+ *     <li> {@link #streamProbableComponentMethods(ClassEntry)}
+ * </ul>
+ */
 public class RecordIndexingService implements JarIndexerService {
 	public static final String ID = "enigma:record_component_indexer";
 
@@ -21,24 +49,108 @@ public class RecordIndexingService implements JarIndexerService {
 		this.visitor = visitor;
 	}
 
+	/**
+	 * @return the {@link MethodEntry} representing the getter of the passed {@code componentField},
+	 * or {@code null} if the passed {@code componentField} is not a record component field
+	 * or if its getter could not be determined; returns both
+	 * {@linkplain #getDefiniteComponentGetter(FieldEntry) definitive} and
+	 * {@linkplain #getProbableComponentGetter(FieldEntry) probable} getters
+	 */
 	@Nullable
 	public MethodEntry getComponentGetter(FieldEntry componentField) {
 		return this.visitor.getComponentGetter(componentField);
 	}
 
+	/**
+	 * @return the {@link FieldEntry} representing the field of the passed {@code componentGetter},
+	 * or {@code null} if the passed {@code componentGetter} is not a record component getter
+	 * or if its field could not be determined; returns both
+	 * {@linkplain #getDefiniteComponentField(MethodEntry) definitive} and
+	 * {@linkplain #getProbableComponentField(MethodEntry) probable} fields
+	 */
 	@Nullable
 	public FieldEntry getComponentField(MethodEntry componentGetter) {
 		return this.visitor.getComponentField(componentGetter);
 	}
 
+	/**
+	 * @return the definitive {@link MethodEntry} representing the getter of the passed {@code componentField},
+	 * or {@code null} if the passed {@code componentField} is not a record component field
+	 * or if its getter could not be definitively determined
+	 */
+	@Nullable
+	public MethodEntry getDefiniteComponentGetter(FieldEntry componentField) {
+		return this.visitor.getDefiniteComponentGetter(componentField);
+	}
+
+	/**
+	 * @return the definitive {@link FieldEntry} representing the field of the passed {@code componentGetter},
+	 * or {@code null} if the passed {@code componentGetter} is not a record component getter
+	 * or if its field could not be definitively determined
+	 */
+	@Nullable
+	public FieldEntry getDefiniteComponentField(MethodEntry componentGetter) {
+		return this.visitor.getDefiniteComponentField(componentGetter);
+	}
+
+	/**
+	 * @return the probable {@link MethodEntry} representing the getter of the passed {@code componentField},
+	 * or {@code null} if the passed {@code componentField} is not a record component field
+	 * or if its getter was not probabilistically determined;
+	 * does not include {@linkplain #getDefiniteComponentGetter(FieldEntry) definitive} getters
+	 */
+	@Nullable
+	public MethodEntry getProbableComponentGetter(FieldEntry componentField) {
+		return this.visitor.getProbableComponentGetter(componentField);
+	}
+
+	/**
+	 * @return the probably {@link FieldEntry} representing the field of the passed {@code componentGetter},
+	 * or {@code null} if the passed {@code componentGetter} is not a record component getter
+	 * or if its field was not probabilistically determined;
+	 * does not include {@linkplain #getDefiniteComponentField(MethodEntry) definitive} fields
+	 */
+	@Nullable
+	public FieldEntry getProbableComponentField(MethodEntry componentGetter) {
+		return this.visitor.getProbableComponentField(componentGetter);
+	}
+
+	/**
+	 * @return a {@link Stream} of component fields of the passed {@code recordEntry};
+	 * there's no uncertainty in getter field determination, so all fields are always included;
+	 * if the passed {@code recordEntry} does not represent a record, the stream is empty
+	 */
 	public Stream<FieldEntry> streamComponentFields(ClassEntry recordEntry) {
 		return this.visitor.streamComponentFields(recordEntry);
 	}
 
+	/**
+	 * @return a {@link Stream} of component getter methods of the passed {@code recordEntry};
+	 * includes both {@linkplain #streamDefiniteComponentMethods(ClassEntry) definitive} and
+	 * {@linkplain #streamProbableComponentMethods(ClassEntry) probable} getters;
+	 * if the passed {@code recordEntry} does not represent a record, the stream is empty
+	 */
 	public Stream<MethodEntry> streamComponentMethods(ClassEntry recordEntry) {
 		return this.visitor.streamComponentMethods(recordEntry);
 	}
 
+	/**
+	 * @return a {@link Stream} of definitive component getter methods of the passed {@code recordEntry};
+	 * if the passed {@code recordEntry} does not represent a record, the stream is empty
+	 */
+	public Stream<MethodEntry> streamDefiniteComponentMethods(ClassEntry recordEntry) {
+		return this.visitor.streamDefiniteComponentMethods(recordEntry);
+	}
+
+	/**
+	 * @return a {@link Stream} of probable component getter methods of the passed {@code recordEntry};
+	 * does not include {@linkplain #streamDefiniteComponentMethods(ClassEntry) definitive} getters;
+	 * if the passed {@code recordEntry} does not represent a record, the stream is empty
+	 */
+	public Stream<MethodEntry> streamProbableComponentMethods(ClassEntry recordEntry) {
+		return this.visitor.streamProbableComponentMethods(recordEntry);
+	}
+
 	@Override
 	public void acceptJar(Set<String> scope, ProjectClassProvider classProvider, JarIndex jarIndex) {
 		for (String className : scope) {

enigma/src/main/java/org/quiltmc/enigma/impl/plugin/RecordIndexingVisitor.java

@@ -28,8 +28,9 @@
 import java.util.Set;
 import java.util.stream.Stream;
 
-// TODO add tests
-// TODO javadoc, including getter uncertainty
+/**
+ * @see RecordIndexingService
+ */
 final class RecordIndexingVisitor extends ClassVisitor {
 	private static final int REQUIRED_GETTER_ACCESS = Opcodes.ACC_PUBLIC;
 	private static final int ILLEGAL_GETTER_ACCESS = Opcodes.ACC_SYNTHETIC | Opcodes.ACC_BRIDGE | Opcodes.ACC_STATIC;
@@ -40,8 +41,7 @@ final class RecordIndexingVisitor extends ClassVisitor {
 	// visitation state fields; cleared in visitEnd()
 	private ClassEntry clazz;
 	private final Set<RecordComponentNode> recordComponents = new HashSet<>();
-	// TODO investigate this; may need to replace clazz with a class stack and to change this to fieldsByNameByClass
-	// this is a multimap because inner classes' fields go in the same map as their outer class's
+	// this is a multimap because proguard can give component fields with different types the same name
 	private final Multimap<String, FieldNode> fieldsByName = HashMultimap.create();
 	private final Multimap<String, MethodNode> methodsByDescriptor = HashMultimap.create();
 
@@ -60,14 +60,18 @@ final class RecordIndexingVisitor extends ClassVisitor {
 		super(Enigma.ASM_VERSION);
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#getComponentGetter(FieldEntry)
+	 */
 	@Nullable
 	public MethodEntry getComponentGetter(FieldEntry componentField) {
 		final MethodEntry definiteGetter = this.definiteComponentGettersByField.get(componentField);
 		return definiteGetter == null ? this.probableComponentGettersByField.get(componentField) : definiteGetter;
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#getComponentField(MethodEntry)
+	 */
 	@Nullable
 	public FieldEntry getComponentField(MethodEntry componentGetter) {
 		final FieldEntry definiteField = this.definiteComponentGettersByField.inverse().get(componentGetter);
@@ -76,49 +80,65 @@ public FieldEntry getComponentField(MethodEntry componentGetter) {
 			: definiteField;
 	}
 
-	// TODO javadoc, prevent directly naming method (always match field)
+	/**
+	 * @see RecordIndexingService#getDefiniteComponentGetter(FieldEntry)
+	 */
 	@Nullable
 	public MethodEntry getDefiniteComponentGetter(FieldEntry componentField) {
 		return this.definiteComponentGettersByField.get(componentField);
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#getDefiniteComponentField(MethodEntry)
+	 */
 	@Nullable
 	public FieldEntry getDefiniteComponentField(MethodEntry componentGetter) {
 		return this.definiteComponentGettersByField.inverse().get(componentGetter);
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#getProbableComponentGetter(FieldEntry)
+	 */
 	@Nullable
 	public MethodEntry getProbableComponentGetter(FieldEntry componentField) {
 		return this.probableComponentGettersByField.get(componentField);
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#getProbableComponentField(MethodEntry)
+	 */
 	@Nullable
 	public FieldEntry getProbableComponentField(MethodEntry componentGetter) {
 		return this.probableComponentGettersByField.inverse().get(componentGetter);
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#streamComponentFields(ClassEntry)
+	 */
 	public Stream<FieldEntry> streamComponentFields(ClassEntry recordEntry) {
 		return this.componentFieldsByClass.get(recordEntry).stream();
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#streamComponentMethods(ClassEntry)
+	 */
 	public Stream<MethodEntry> streamComponentMethods(ClassEntry recordEntry) {
 		return Stream.concat(
 			this.definiteComponentGettersByClass.get(recordEntry).stream(),
 			this.probableComponentGettersByClass.get(recordEntry).stream()
 		);
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#streamDefiniteComponentMethods(ClassEntry)
+	 */
 	public Stream<MethodEntry> streamDefiniteComponentMethods(ClassEntry recordEntry) {
 		return this.definiteComponentGettersByClass.get(recordEntry).stream();
 	}
 
-	// TODO javadoc
+	/**
+	 * @see RecordIndexingService#streamProbableComponentMethods(ClassEntry)
+	 */
 	public Stream<MethodEntry> streamProbableComponentMethods(ClassEntry recordEntry) {
 		return this.probableComponentGettersByClass.get(recordEntry).stream();
 	}