[evolution-data-server/openismus-work] EBookQuery/EPhoneNumber: Enhanced documentation

[Tristan Van Berkom <tvb src gnome org>]

commit 43cc3cb74c7d5f2d49a2429b439145a25b064752
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Fri Feb 22 22:44:15 2013 +0900

    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.
    
    Conflicts:
    
        addressbook/libebook-contacts/e-book-query.h

 addressbook/libebook-contacts/e-book-query.h   |   21 +++++++++----------
 addressbook/libebook-contacts/e-phone-number.h |   25 ++++++++++++++++-------
 2 files changed, 27 insertions(+), 19 deletions(-)
---
diff --git a/addressbook/libebook-contacts/e-book-query.h b/addressbook/libebook-contacts/e-book-query.h
index 12a1662..49e8b53 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 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.
+ *
+ * <example>
+ * <title>Some examples of phone number matches</title>
+ * <para>
  * 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 {
  *   </tr>
  *  </tbody>
  * </informaltable>
+ * </para>
+ * </example>
  *
  * Since: 3.8
  **/