Updating docs to: (#1605)

- make them more consistent with each other
- explain why the empty string is sometimes returned when geocoding

cpp/src/phonenumbers/geocoding/phonenumber_offline_geocoder.h

@@ -65,10 +65,13 @@ class PhoneNumberOfflineGeocoder {
   // Returns a text description for the given phone number, in the language
   // provided. The description might consist of the name of the country where
   // the phone number is from, or the name of the geographical area the phone
-  // number is from if more detailed information is available.
+  // number is from if more detailed information is available. Returns an empty
+  // string if the number could come from multiple countries, or the country
+  // code is in fact invalid.
   //
   // This method assumes the validity of the number passed in has already been
-  // checked.
+  // checked, and that the number is suitable for geocoding. We consider
+  // fixed-line and mobile numbers possible candidates for geocoding.
   string GetDescriptionForValidNumber(const PhoneNumber& number,
                                       const Locale& language) const;
 
@@ -85,11 +88,12 @@ class PhoneNumberOfflineGeocoder {
   // "United States".
   //
   // This method assumes the validity of the number passed in has already been
-  // checked.
+  // checked, and that the number is suitable for geocoding. We consider
+  // fixed-line and mobile numbers possible candidates for geocoding.
   //
   // user_region is the region code for a given user. This region will be
   // omitted from the description if the phone number comes from this region. It
-  // is a two-letter uppercase ISO country code as defined by ISO 3166-1.
+  // should be a two-letter uppercase ISO country code as defined by ISO 3166-1.
   string GetDescriptionForValidNumber(const PhoneNumber& number,
       const Locale& language, const string& user_region) const;
 
@@ -133,7 +137,7 @@ class PhoneNumberOfflineGeocoder {
   // script is a four-letter titlecase (the first letter is uppercase and the
   // rest of the letters are lowercase) ISO script codes as defined in ISO
   // 15924.
-  // region is a two-letter uppercase ISO country codes as defined by ISO
+  // region should be a two-letter uppercase ISO country codes as defined by ISO
   // 3166-1.
   const char* GetAreaDescription(const PhoneNumber& number, const string& lang,
                                  const string& script,

java/geocoder/src/com/google/i18n/phonenumbers/geocoding/PhoneNumberOfflineGeocoder.java

@@ -72,9 +72,9 @@ public class PhoneNumberOfflineGeocoder {
       String regionWhereNumberIsValid = "ZZ";
       for (String regionCode : regionCodes) {
         if (phoneUtil.isValidNumberForRegion(number, regionCode)) {
+          // If the number has already been found valid for one region, then we don't know which
+          // region it belongs to so we return nothing.
           if (!regionWhereNumberIsValid.equals("ZZ")) {
-            // If we can't assign the phone number as definitely belonging to only one territory,
-            // then we return nothing.
             return "";
           }
           regionWhereNumberIsValid = regionCode;
@@ -105,7 +105,9 @@ public class PhoneNumberOfflineGeocoder {
    *
    * @param number  a valid phone number for which we want to get a text description
    * @param languageCode  the language code for which the description should be written
-   * @return  a text description for the given language code for the given phone number
+   * @return  a text description for the given language code for the given phone number, or an
+   *     empty string if the number could come from multiple countries, or the country code is
+   *     in fact invalid
    */
   public String getDescriptionForValidNumber(PhoneNumber number, Locale languageCode) {
     String langStr = languageCode.getLanguage();
@@ -153,10 +155,11 @@ public class PhoneNumberOfflineGeocoder {
    * @param number  the phone number for which we want to get a text description
    * @param languageCode  the language code for which the description should be written
    * @param userRegion  the region code for a given user. This region will be omitted from the
-   *     description if the phone number comes from this region. It is a two-letter uppercase ISO
-   *     country code as defined by ISO 3166-1.
-   * @return  a text description for the given language code for the given phone number, or empty
-   *     string if the number passed in is invalid
+   *     description if the phone number comes from this region. It should be a two-letter
+   *     uppercase ISO country code as defined by ISO 3166-1.
+   * @return  a text description for the given language code for the given phone number, or an
+   *     empty string if the number could come from multiple countries, or the country code is
+   *     in fact invalid
    */
   public String getDescriptionForValidNumber(PhoneNumber number, Locale languageCode,
                                              String userRegion) {
@@ -180,7 +183,7 @@ public class PhoneNumberOfflineGeocoder {
    * @param number  the phone number for which we want to get a text description
    * @param languageCode  the language code for which the description should be written
    * @return  a text description for the given language code for the given phone number, or empty
-   *     string if the number passed in is invalid
+   *     string if the number passed in is invalid or could belong to multiple countries
    */
   public String getDescriptionForNumber(PhoneNumber number, Locale languageCode) {
     PhoneNumberType numberType = phoneUtil.getNumberType(number);
@@ -199,10 +202,10 @@ public class PhoneNumberOfflineGeocoder {
    * @param number  the phone number for which we want to get a text description
    * @param languageCode  the language code for which the description should be written
    * @param userRegion  the region code for a given user. This region will be omitted from the
-   *     description if the phone number comes from this region. It is a two-letter uppercase ISO
-   *     country code as defined by ISO 3166-1.
+   *     description if the phone number comes from this region. It should be a two-letter
+   *     uppercase ISO country code as defined by ISO 3166-1.
    * @return  a text description for the given language code for the given phone number, or empty
-   *     string if the number passed in is invalid
+   *     string if the number passed in is invalid or could belong to multiple countries
    */
   public String getDescriptionForNumber(PhoneNumber number, Locale languageCode,
                                         String userRegion) {

pending_code_changes.txt

@@ -1 +1,3 @@
-
+Code changes:
+ - Doc fix for PhoneNumberOfflineGeocoder to explain the cases where an empty
+   string might be returned.