Bug 1045053 - Part 0: add descriptive comments for locale handling. r=me

mobile/android/base/BrowserLocaleManager.java

@@ -329,6 +329,9 @@ public class BrowserLocaleManager implements LocaleManager {
         return GeckoSharedPrefs.forApp(context);
     }
 
+    /**
+     * @return the persisted locale in Java format: "en_US".
+     */
     private String getPersistedLocale(Context context) {
         final SharedPreferences settings = getSharedPreferences(context);
         final String locale = settings.getString(PREF_LOCALE, "");
@@ -363,6 +366,9 @@ public class BrowserLocaleManager implements LocaleManager {
      * Returns the persisted locale if it differed.
      *
      * Does not notify Gecko.
+     *
+     * @param localeCode a locale string in Java format: "en_US".
+     * @return if it differed, a locale string in Java format: "en_US".
      */
     private String updateLocale(Context context, String localeCode) {
         // Fast path.
@@ -376,6 +382,9 @@ public class BrowserLocaleManager implements LocaleManager {
         return updateLocale(context, locale);
     }
 
+    /**
+     * @return the Java locale string: e.g., "en_US".
+     */
     private String updateLocale(Context context, final Locale locale) {
         // Fast path.
         if (Locale.getDefault().equals(locale)) {

mobile/android/base/GeckoApp.java

@@ -1317,6 +1317,7 @@ public abstract class GeckoApp
                 final String profilePath = getProfile().getDir().getAbsolutePath();
                 final EventDispatcher dispatcher = EventDispatcher.getInstance();
 
+                // Both of these are Java-format locale strings: "en_US", not "en-US".
                 final String osLocale = Locale.getDefault().toString();
                 String appLocale = localeManager.getAndApplyPersistedLocale(GeckoApp.this);
                 Log.d(LOGTAG, "OS locale is " + osLocale + ", app locale is " + appLocale);