improve carrier id documentation am: 0962fe946e am: 462d40193f

am: 8a2df338db

Change-Id: I2b73672531f657aa983ded17834b0452321132e2

2 files changed, 16 insertions, 10 deletions

diff --git a/README b/README
index bf9f552..4467aa9 100644
--- a/README
+++ b/README
@@ -9,7 +9,7 @@ folder. Two ways to configure per-network configuration. Preferred way is
 carrier_config_carrierid_<carrierid>_<carriername>.xml
 AOSP carrier ID assignments can be found at
 https://android.googlesource.com/platform/packages/providers/TelephonyProvider/+/master/assets/carrier_list.textpb
-another way is carrier_config_mccmnc_<mccmnc>.xml
+use carrier_config_mccmnc_<mccmnc>.xml only if there is no matching carrier id.
 
 This app uses a CarrierIdentifier to read the appropriate config snippets from the assets folder.
 
diff --git a/src/com/android/carrierconfig/DefaultCarrierConfigService.java b/src/com/android/carrierconfig/DefaultCarrierConfigService.java
index 3458df4..b709040 100644
--- a/src/com/android/carrierconfig/DefaultCarrierConfigService.java
+++ b/src/com/android/carrierconfig/DefaultCarrierConfigService.java
@@ -48,7 +48,13 @@ public class DefaultCarrierConfigService extends CarrierService {
      * Returns per-network overrides for carrier configuration.
      *
      * This returns a carrier config bundle appropriate for the given carrier by reading data from
-     * files in our assets folder. First we look for file named after
+     * files in our assets folder. Config files in assets folder are carrier-id-indexed
+     * {@link TelephonyManager#getSimCarrierId()}. NOTE: config files named after mccmnc
+     * are for those without a matching carrier id and should be renamed to carrier id once the
+     * missing IDs are added to
+     * <a href="https://android.googlesource.com/platform/packages/providers/TelephonyProvider/+/master/assets/carrier_list.textpb">carrier id list</a>
+     *
+     * First, look for file named after
      * carrier_config_carrierid_<carrierid>_<carriername>.xml if carrier id is not
      * {@link TelephonyManager#UNKNOWN_CARRIER_ID}. Note <carriername> is to improve the
      * readability which should not be used to search asset files. If there is no configuration,
@@ -143,26 +149,26 @@ public class DefaultCarrierConfigService extends CarrierService {
      * by {@link PersistableBundle#restoreFromXml}. All the matching bundles will be flattened and
      * returned as a single bundle.</p>
      *
-     * <p>Here is an example document. The second bundle will be applied to the first only if the
-     * GID1 is ABCD.
+     * <p>Here is an example document in vendor.xml.
      * <pre>{@code
      * <carrier_config_list>
-     *     <carrier_config>
+     *     <carrier_config cid="1938" name="verizon">
      *         <boolean name="voicemail_notification_persistent_bool" value="true" />
      *     </carrier_config>
-     *     <carrier_config gid1="ABCD">
+     *     <carrier_config cid="1788" name="sprint">
      *         <boolean name="voicemail_notification_persistent_bool" value="false" />
      *     </carrier_config>
      * </carrier_config_list>
      * }</pre></p>
      *
-     * <p>Here is another example document in vendor.xml.
+     * <p>Here is an example document. The second bundle will be applied to the first only if the
+     * GID1 is ABCD.
      * <pre>{@code
      * <carrier_config_list>
-     *     <carrier_config cid="1938" name="verizon">
+     *     <carrier_config>
      *         <boolean name="voicemail_notification_persistent_bool" value="true" />
      *     </carrier_config>
-     *     <carrier_config cid="1788" name="sprint">
+     *     <carrier_config gid1="ABCD">
      *         <boolean name="voicemail_notification_persistent_bool" value="false" />
      *     </carrier_config>
      * </carrier_config_list>
@@ -170,7 +176,7 @@ public class DefaultCarrierConfigService extends CarrierService {
      *
      * @param parser an XmlPullParser pointing at the beginning of the document.
      * @param id the details of the SIM operator used to filter parts of the document. If read from
-     *           file named after carrier id, this will be set to {@null code} as no filter match
+     *           files named after carrier id, this will be set to {@null code} as no filter match
      *           needed.
      * @return a possibly empty PersistableBundle containing the config values.
      */