From 5053013dfaf93cc75f07adb42ccfa5469f09dab6 Mon Sep 17 00:00:00 2001 From: lararennie Date: Thu, 2 Mar 2017 14:08:48 +0100 Subject: [PATCH] Updating docs to: (#1605) - make them more consistent with each other - explain why the empty string is sometimes returned when geocoding --- .../geocoding/phonenumber_offline_geocoder.h | 14 +++++++---- .../geocoding/PhoneNumberOfflineGeocoder.java | 25 +++++++++++-------- pending_code_changes.txt | 4 ++- 3 files changed, 26 insertions(+), 17 deletions(-) diff --git a/cpp/src/phonenumbers/geocoding/phonenumber_offline_geocoder.h b/cpp/src/phonenumbers/geocoding/phonenumber_offline_geocoder.h index 8022b7755..c31b03b15 100644 --- a/cpp/src/phonenumbers/geocoding/phonenumber_offline_geocoder.h +++ b/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, diff --git a/java/geocoder/src/com/google/i18n/phonenumbers/geocoding/PhoneNumberOfflineGeocoder.java b/java/geocoder/src/com/google/i18n/phonenumbers/geocoding/PhoneNumberOfflineGeocoder.java index d0869e5b3..1cfcac383 100644 --- a/java/geocoder/src/com/google/i18n/phonenumbers/geocoding/PhoneNumberOfflineGeocoder.java +++ b/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) { diff --git a/pending_code_changes.txt b/pending_code_changes.txt index 8b1378917..754e54e4a 100644 --- a/pending_code_changes.txt +++ b/pending_code_changes.txt @@ -1 +1,3 @@ - +Code changes: + - Doc fix for PhoneNumberOfflineGeocoder to explain the cases where an empty + string might be returned.