From: Tristan Van Berkom Date: Fri, 22 Feb 2013 13:44:15 +0000 (+0900) Subject: EBookQuery/EPhoneNumber: Enhanced documentation X-Git-Tag: upstream/3.7.91~95 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=b65a9759185fa759de55ab4ef7165034a655c44f;p=platform%2Fupstream%2Fevolution-data-server.git EBookQuery/EPhoneNumber: Enhanced documentation EBookQuery documentation simplified to reference documentation from EPhoneNumber docs specifically. EPhoneNumber documentation enhanced to be more descriptive in terms of the match type strengths possible. --- diff --git a/addressbook/libebook-contacts/e-book-query.h b/addressbook/libebook-contacts/e-book-query.h index 10ea1a4..235e2d6 100644 --- a/addressbook/libebook-contacts/e-book-query.h +++ b/addressbook/libebook-contacts/e-book-query.h @@ -20,20 +20,19 @@ typedef struct EBookQuery EBookQuery; * @E_BOOK_QUERY_CONTAINS: check if a field contains the test value * @E_BOOK_QUERY_BEGINS_WITH: check if a field starts with the test value * @E_BOOK_QUERY_ENDS_WITH: check if a field ends with the test value - * @E_BOOK_QUERY_EQUALS_PHONE_NUMBER: check that a field and the test value - * match exactly when interpreted as phone number, that is after stripping - * 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 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. + * @E_BOOK_QUERY_EQUALS_PHONE_NUMBER: check if a field matches with a value tested + * using e_phone_number_compare_strings(), the match must be of strenth %E_PHONE_NUMBER_MATCH_EXACT + * for this query to return any matches. + * @E_BOOK_QUERY_EQUALS_NATIONAL_PHONE_NUMBER: check if a field matches with a value tested + * using e_phone_number_compare_strings(), the match must be at least of strength %E_PHONE_NUMBER_MATCH_NATIONAL + * for this query to return any matches. + * @E_BOOK_QUERY_EQUALS_SHORT_PHONE_NUMBER: check if a field matches with a value tested + * using e_phone_number_compare_strings(), the match must be at least of strength %E_PHONE_NUMBER_MATCH_SHORT + * for this query to return any matches. * * The kind of test a query created by e_book_query_field_test() shall perform. * - * See also: E_PHONE_NUMBER_MATCH_EXACT, E_PHONE_NUMBER_MATCH_NATIONAL and - * E_PHONE_NUMBER_MATCH_SHORT. + * See also: e_phone_number_compare_strings(). **/ typedef enum { E_BOOK_QUERY_IS, diff --git a/addressbook/libebook-contacts/e-phone-number.h b/addressbook/libebook-contacts/e-phone-number.h index 3c39a40..cba7559 100644 --- a/addressbook/libebook-contacts/e-phone-number.h +++ b/addressbook/libebook-contacts/e-phone-number.h @@ -66,15 +66,22 @@ 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 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. + * @E_PHONE_NUMBER_MATCH_EXACT: The phone numbers matched exactly. Two phone number strings are an exact match + * if the country code, national phone number, presence of a leading zero for Italian numbers and any + * extension present are the same. + * @E_PHONE_NUMBER_MATCH_NATIONAL: The national phone number matched. Two phone number strings match at + * this strength if either or both has no region specified, and the national phone number + * and extensions are the same. + * @E_PHONE_NUMBER_MATCH_SHORT: The weakest sort of match. Two phone numbers match at + * this strength if either or both has no region specified, or the region specified is the same, and one national + * phone number could be a shorter version of the other number. This includes the case where one has an extension specified, + * and the other does not. * - * The quality of a phone number match. - + * The strength of a phone number match. + * + * + * Some examples of phone number matches + * * 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" @@ -125,6 +132,8 @@ typedef enum { * * * + * + * * * Since: 3.8 **/