Add documentation for the different files created by hiddenapi

Test: m nothing
Bug: 178361284
Change-Id: Id55646b9d4b7bc1acdb4ed6a6dd4456b746eb54c

1 files changed, 33 insertions, 3 deletions

diff --git a/java/hiddenapi.go b/java/hiddenapi.go
index 71f1e576d..c7dac8fec 100644
--- a/java/hiddenapi.go
+++ b/java/hiddenapi.go
@@ -28,10 +28,40 @@ var hiddenAPIGenerateCSVRule = pctx.AndroidStaticRule("hiddenAPIGenerateCSV", bl
 }, "outFlag", "stubAPIFlags")
 
 type hiddenAPI struct {
-	bootDexJarPath  android.Path
-	flagsCSVPath    android.Path
-	indexCSVPath    android.Path
+	// The path to the dex jar that is in the boot class path. If this is nil then the associated
+	// module is not a boot jar, but could be one of the <x>-hiddenapi modules that provide additional
+	// annotations for the <x> boot dex jar but which do not actually provide a boot dex jar
+	// themselves.
+	bootDexJarPath android.Path
+
+	// The path to the CSV file that contains mappings from Java signature to various flags derived
+	// from annotations in the source, e.g. whether it is public or the sdk version above which it
+	// can no longer be used.
+	//
+	// It is created by the Class2NonSdkList tool which processes the .class files in the class
+	// implementation jar looking for UnsupportedAppUsage and CovariantReturnType annotations. The
+	// tool also consumes the hiddenAPISingletonPathsStruct.stubFlags file in order to perform
+	// consistency checks on the information in the annotations and to filter out bridge methods
+	// that are already part of the public API.
+	flagsCSVPath android.Path
+
+	// The path to the CSV file that contains mappings from Java signature to the value of properties
+	// specified on UnsupportedAppUsage annotations in the source.
+	//
+	// Like the flagsCSVPath file this is also created by the Class2NonSdkList in the same way.
+	// Although the two files could potentially be created in a single invocation of the
+	// Class2NonSdkList at the moment they are created using their own invocation, with the behavior
+	// being determined by the property that is used.
 	metadataCSVPath android.Path
+
+	// The path to the CSV file that contains mappings from Java signature to source location
+	// information.
+	//
+	// It is created by the merge_csv tool which processes the class implementation jar, extracting
+	// all the files ending in .uau (which are CSV files) and merges them together. The .uau files are
+	// created by the unsupported app usage annotation processor during compilation of the class
+	// implementation jar.
+	indexCSVPath android.Path
 }
 
 func (h *hiddenAPI) flagsCSV() android.Path {