Add documentation on ExtractMarkerInformation callbacks
Fixes: b/283847513
Change-Id: Ia4b3e7a11313ec39e3059f8954079410986f57f3
diff --git a/src/main/java/com/android/tools/r8/ExtractMarkerCommand.java b/src/main/java/com/android/tools/r8/ExtractMarkerCommand.java
index ac084da..831530f 100644
--- a/src/main/java/com/android/tools/r8/ExtractMarkerCommand.java
+++ b/src/main/java/com/android/tools/r8/ExtractMarkerCommand.java
@@ -55,6 +55,9 @@
/**
* Add program files to extract marker information from.
*
+ * <p>Each file added here will result in exactly one callback to {@link
+ * MarkerInfoConsumer#acceptMarkerInfo}.
+ *
* <p>All program files supported by the input and output of D8/R8 can be passed here.
*/
public Builder addProgramFiles(Collection<Path> programFiles) {
@@ -62,13 +65,23 @@
return this;
}
- /** Add dex encoded bytes to extract marker information from. */
+ /**
+ * Add dex encoded bytes to extract marker information from.
+ *
+ * <p>Each data & origin pair added here will result in exactly one callback to {@link
+ * MarkerInfoConsumer#acceptMarkerInfo}.
+ */
public Builder addDexProgramData(byte[] data, Origin origin) {
dexData.add(new Pair<>(origin, data));
return this;
}
- /** Add classfile encoded bytes to extract marker information from. */
+ /**
+ * Add classfile encoded bytes to extract marker information from.
+ *
+ * <p>Each data & origin pair added here will result in exactly one callback to {@link
+ * MarkerInfoConsumer#acceptMarkerInfo}.
+ */
public Builder addClassProgramData(byte[] data, Origin origin) {
cfData.add(new Pair<>(origin, data));
return this;
diff --git a/src/main/java/com/android/tools/r8/MarkerInfoConsumer.java b/src/main/java/com/android/tools/r8/MarkerInfoConsumer.java
index 48e4a30..87342e4 100644
--- a/src/main/java/com/android/tools/r8/MarkerInfoConsumer.java
+++ b/src/main/java/com/android/tools/r8/MarkerInfoConsumer.java
@@ -7,7 +7,19 @@
@Keep
public interface MarkerInfoConsumer {
+ /**
+ * Callback that provides the marker information of a resource.
+ *
+ * <p>This callback is called exactly once for each resource in the {@link ExtractMarkerCommand},
+ * also when no marker information is present in that resource.
+ */
void acceptMarkerInfo(MarkerInfoConsumerData data);
+ /**
+ * Callback to inform the extraction of marker information is complete.
+ *
+ * <p>After the callback is invoked no further calls to {@link
+ * MarkerInfoConsumer#acceptMarkerInfo} will occur.
+ */
void finished();
}
