Improve docs around srcgen
Change-Id: Ib64e69a374abd551c1212ea801799e4834d2a063
diff --git a/README.android b/README.android
new file mode 100644
index 0000000..5f8ff53
--- /dev/null
+++ b/README.android
@@ -0,0 +1,15 @@
+This repo contains Android's copy of ICU4C and ICU4J and associated tools and code.
+
+Directories
+===========
+
+icu4j/,icu4c/ - ICU4J and ICU4C with Google and Android-specific patches applied.
+
+android_icu4j/ - A transformed copy of icu4j source repackaged into android.icu.
+ This is the copy of ICU4J used in the Android platform.
+ IMPORTANT NOTE: Do not make changes to this code directly.
+ See tools/README.android.
+
+android_utils/ - ICU4C runtime initialization / Android integration code.
+
+tools/ - Code / data maintenance tools. See tools/README.android.
diff --git a/tools/README.android b/tools/README.android
index 173f463..bf91cf2 100644
--- a/tools/README.android
+++ b/tools/README.android
@@ -18,9 +18,34 @@
ICU and CTS tests for libcore should be run before and
after.
-Version upgrade tools
-=====================
+Source code updates
+===================
-srcgen
- - tools to generate Android's copy of the ICU source code in
- libcore/android_icu4j.
+The source code in android_icu4j is generated from the code in icu4j. Do not change the code
+in android_icu4j directly: instead you change the icu4j source or the rules used to generate
+android_icu4j.
+
+All changes made to icu4j should be accompanied by changes in android_icu4j and vice versa.
+
+Applying patches to ICU4J
+-------------------------
+
+After making changes to icu4j (e.g. after applying upstream patches):
+
+source build/envsetup.sh
+lunch
+
+cd external/icu/tools/srcgen
+./generate_android_icu4j.sh
+
+The code in android_icu4j will be regenerated and should contain the changes you made
+in icu4j. Confirm the diffs are what you intended. Commit both at the same time.
+
+Modifying the code gen
+----------------------
+
+android_icu4j is generated using a Java tool found in tools/srcgen.
+
+The "rules" that transform the source are configured in
+src/main/java/com/android/icu4j/srcgen/Icu4jTransform.java.
+