[evolution-data-server] libebook: Improve phone-number docs and messages

From: Mathias Hasselmann <hasselmm src gnome org>
To: commits-list gnome org
Cc:
Subject: [evolution-data-server] libebook: Improve phone-number docs and messages
Date: Thu, 7 Feb 2013 08:27:33 +0000 (UTC)
commit f78c7257bf9a44cc9c654223e6d368c6fa44ba0b
Author: Mathias Hasselmann <mathias openismus com>
Date:   Wed Feb 6 19:07:06 2013 +0100

    libebook: Improve phone-number docs and messages
    
    Be more strict about the terms "country calling code" which
    relates to phone numbers, and "two-letter country code" which
    identifies region.

 addressbook/libebook/e-book-query.h             |    2 +-
 addressbook/libebook/e-phone-number-private.cpp |    4 +-
 addressbook/libebook/e-phone-number.c           |   28 ++++++++++++----------
 addressbook/libebook/e-phone-number.h           |   28 ++++++++++++----------
 4 files changed, 33 insertions(+), 29 deletions(-)
---
diff --git a/addressbook/libebook/e-book-query.h b/addressbook/libebook/e-book-query.h
index 82342b4..6e04f78 100644
--- a/addressbook/libebook/e-book-query.h
+++ b/addressbook/libebook/e-book-query.h
@@ -25,7 +25,7 @@ typedef struct EBookQuery EBookQuery;
  * formatting like dashes, dots and spaces. See E_PHONE_NUMBER_MATCH_EXACT.
  * @E_BOOK_QUERY_EQUALS_NATIONAL_PHONE_NUMBER: check that a field and the
  * test value match when interpreted as phone number, except for the
- * (omitted) country code.
+ * (omitted) country calling code.
  * @E_BOOK_QUERY_EQUALS_SHORT_PHONE_NUMBER: check that a field and the test
  * value match is the sense that both values appear to be phone numbers,
  * and one might be a part (suffix) of the other.
diff --git a/addressbook/libebook/e-phone-number-private.cpp b/addressbook/libebook/e-phone-number-private.cpp
index 99857df..781e5b7 100644
--- a/addressbook/libebook/e-phone-number-private.cpp
+++ b/addressbook/libebook/e-phone-number-private.cpp
@@ -91,13 +91,13 @@ e_phone_number_error_code (PhoneNumberUtil::ErrorType error)
 static std::string
 e_phone_number_make_region_code (const gchar *region_code)
 {
-	/* Get country code from current locale's address facet if supported */
+	/* Get two-letter country code from current locale's address facet if supported */
 #if HAVE__NL_ADDRESS_COUNTRY_AB2
 	if (region_code == NULL || region_code[0] == '\0')
 		region_code = nl_langinfo (_NL_ADDRESS_COUNTRY_AB2);
 #endif /* HAVE__NL_ADDRESS_COUNTRY_AB2 */
 
-	/* Extract country code from current locale id if needed */
+	/* Extract two-letter country code from current locale id if needed */
 	if (region_code == NULL || region_code[0] == '\0') {
 		/* From outside this is a C library, so we better consult the
 		 * C infrastructure instead of std::locale, which might divert. */
diff --git a/addressbook/libebook/e-phone-number.c b/addressbook/libebook/e-phone-number.c
index cff75e2..95beef4 100644
--- a/addressbook/libebook/e-phone-number.c
+++ b/addressbook/libebook/e-phone-number.c
@@ -46,9 +46,9 @@ e_phone_number_error_to_string (EPhoneNumberError code)
 	case E_PHONE_NUMBER_ERROR_NOT_A_NUMBER:
 		return _("Not a phone number");
 	case E_PHONE_NUMBER_ERROR_INVALID_COUNTRY_CODE:
-		return _("Invalid country code");
+		return _("Invalid country calling code");
 	case E_PHONE_NUMBER_ERROR_TOO_SHORT_AFTER_IDD:
-		return _("Remaining text after the country code is to short for a phone number");
+		return _("Remaining text after the country calling code is to short for a phone number");
 	case E_PHONE_NUMBER_ERROR_TOO_SHORT:
 		return _("Text is too short for a phone number");
 	case E_PHONE_NUMBER_ERROR_TOO_LONG:
@@ -94,14 +94,16 @@ e_phone_number_is_supported (void)
 
 /**
  * e_phone_number_get_country_code_for_region:
- * @region_code: (allow-none): a 2-letter country code, or %NULL
+ * @region_code: (allow-none): a two-letter country code, or %NULL
  *
- * Returns the preferred country code for @region_code, e.g. 358 for "fi".
+ * Retrieves the preferred country calling code for @region_code,
+ * e.g. 358 for "fi".
  *
  * If %NULL is passed for @region_code the default region as returned by
  * e_phone_number_get_default_region() is used.
  *
- * Returns: a valid country code, or zero if an unknown region code was passed.
+ * Returns: a valid country calling code, or zero if an unknown region
+ * code was passed.
  *
  * Since: 3.8
  */
@@ -123,7 +125,7 @@ e_phone_number_get_country_code_for_region (const gchar *region_code)
 /**
  * e_phone_number_get_default_region:
  *
- * Retrieves the current 2-letter region code that's used by default for
+ * Retrieves the current two-letter country code that's used by default for
  * parsing phone numbers in e_phone_number_from_string(). It can be useful
  * to store this number before parsing a bigger number of phone numbers.
  *
@@ -133,7 +135,7 @@ e_phone_number_get_country_code_for_region (const gchar *region_code)
  * locale name configured for %LC_ADDRESS is parsed.
  *
  * Returns: (transfer full): a newly allocated string containing the
- * current locale's 2-letter code for phone number parsing.
+ * current locale's two-letter code for phone number parsing.
  *
  * Since: 3.8
  */
@@ -155,14 +157,14 @@ e_phone_number_get_default_region (void)
 /**
  * e_phone_number_from_string:
  * @phone_number: the phone number to parse
- * @region_code: (allow-none): a 2-letter country code, or %NULL
+ * @region_code: (allow-none): a two-letter country code, or %NULL
  * @error: (out): a #GError to set an error, if any
  *
  * Parses the string passed in @phone_number. Note that no validation is
  * performed whether the recognized phone number is valid for a particular
  * region.
  *
- * The 2-letter country code passed in @region_code only is used if the
+ * The two-letter country code passed in @region_code only is used if the
  * @phone_number is not written in international format. The application's
  * default region as returned by e_phone_number_get_default_region() is used
  * if @region_code is %NULL.
@@ -224,11 +226,11 @@ e_phone_number_to_string (const EPhoneNumber *phone_number,
  * @phone_number: the phone number to query
  * @source: an optional location for storing the phone number's origin, or %NULL
  *
- * Queries the @phone_number's country code and optionally stores the country code's
- * origin in @source. For instance when parsing "+1-617-5423789" this function
- * would return one and assing E_PHONE_NUMBER_COUNTRY_FROM_FQTN to @source.
+ * Queries the @phone_number's country calling code and optionally stores the country
+ * calling code's origin in @source. For instance when parsing "+1-617-5423789" this
+ * function would return one and assing E_PHONE_NUMBER_COUNTRY_FROM_FQTN to @source.
  *
- * Returns: A valid country code, or zero if no country code is known.
+ * Returns: A valid country calling code, or zero if no code is known.
  *
  * Since: 3.8
  **/
diff --git a/addressbook/libebook/e-phone-number.h b/addressbook/libebook/e-phone-number.h
index a9d07e9..a4c6a40 100644
--- a/addressbook/libebook/e-phone-number.h
+++ b/addressbook/libebook/e-phone-number.h
@@ -48,7 +48,7 @@ G_BEGIN_DECLS
  * @E_PHONE_NUMBER_FORMAT_INTERNATIONAL: a formatted phone number always
  * starting with the country calling code: "+49 30 55667788".
  * @E_PHONE_NUMBER_FORMAT_NATIONAL: a formatted phone number in national
- * scope, that is without country code: "(030) 55667788".
+ * scope, that is without country calling code: "(030) 55667788".
  * @E_PHONE_NUMBER_FORMAT_RFC3966: a tel: URL according to RFC 3966:
  * "tel:+49-30-55667788".
  *
@@ -67,18 +67,19 @@ typedef enum {
  * EPhoneNumberMatch:
  * @E_PHONE_NUMBER_MATCH_NONE: The phone numbers did not match.
  * @E_PHONE_NUMBER_MATCH_EXACT: The phone numbers matched exactly.
- * @E_PHONE_NUMBER_MATCH_NATIONAL: There was no country code for at least
- * one of the numbers, but the national parts matched.
- * @E_PHONE_NUMBER_MATCH_SHORT: There was no country code for at least
- * one of the numbers, but one number might be part (suffix) of the other.
+ * @E_PHONE_NUMBER_MATCH_NATIONAL: There was no country calling code
+ * for at least one of the numbers, but the national parts matched.
+ * @E_PHONE_NUMBER_MATCH_SHORT: There was no country calling code for
+ * at least one of the numbers, but one number might be part (suffix)
+ * of the other.
  *
  * The quality of a phone number match.
 
  * Let's consider the phone number "+1-221-5423789", then comparing with
  * "+1.221.542.3789" we have get E_PHONE_NUMBER_MATCH_EXACT because country
  * code, region code and local number are matching. Comparing with "2215423789"
- * will result in E_PHONE_NUMBER_MATCH_NATIONAL because the country code is
- * missing, but the national portion is matching. Finally comparing with
+ * will result in E_PHONE_NUMBER_MATCH_NATIONAL because the country calling code
+ * is missing, but the national portion is matching. Finally comparing with
  * "5423789" gives E_PHONE_NUMBER_MATCH_SHORT. For more detail have a look at
  * the following table:
  *
@@ -141,10 +142,10 @@ typedef enum {
  * @E_PHONE_NUMBER_ERROR_UNKNOWN: the phone number parser reported an yet
  * unkown error code.
  * @E_PHONE_NUMBER_ERROR_INVALID_COUNTRY_CODE: the supplied phone number has an
- * invalid country code.
+ * invalid country calling code.
  * @E_PHONE_NUMBER_ERROR_NOT_A_NUMBER: the supplied text is not a phone number.
  * @E_PHONE_NUMBER_ERROR_TOO_SHORT_AFTER_IDD: the remaining text after the
- * country code is to short for a phone number.
+ * country calling code is to short for a phone number.
  * @E_PHONE_NUMBER_ERROR_TOO_SHORT: the text is too short for a phone number.
  * @E_PHONE_NUMBER_ERROR_TOO_LONG: the text is too long for a phone number.
  *
@@ -165,15 +166,16 @@ typedef enum {
 /**
  * EPhoneNumberCountrySource:
  * @E_PHONE_NUMBER_COUNTRY_FROM_FQTN: the EPhoneNumber was build from a
- * fully qualified telephone number that contained a valid country code
+ * fully qualified telephone number that contained a valid country
+ * calling code
  * @E_PHONE_NUMBER_COUNTRY_FROM_IDD: the parsed phone number started
  * with the current locale's international call prefix, followed by a
- * valid country code
+ * valid country calling code
  * @E_PHONE_NUMBER_COUNTRY_FROM_DEFAULT: the parsed phone didn't start
- * with a (recognizable) country code, the country code was chosen by
+ * with a (recognizable) country calling code, the code was chosen by
  * checking the current locale settings
  *
- * The origin of a parsed EPhoneNumber's country code.
+ * The origin of a parsed EPhoneNumber's country calling code.
  *
  * Since: 3.8
  **/
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]