[evolution-data-server/openismus-phonenumber-work] docs: Improve phone-utils documentation

[Mathias Hasselmann <hasselmm src gnome org>]

commit 3ea3e1bd4b1fb5a824edf91e1693a6ab1d89839f
Author: Mathias Hasselmann <mathias openismus com>
Date:   Fri Dec 7 15:51:40 2012 +0100

    docs: Improve phone-utils documentation

 docs/reference/libedataserver/Makefile.am          |    2 +
 .../libedataserver/libedataserver-sections.txt     |    2 +
 libedataserver/e-phone-utils.h                     |   60 +++++++++++++++++++-
 3 files changed, 61 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/libedataserver/Makefile.am b/docs/reference/libedataserver/Makefile.am
index 7a48782..5fff1ff 100644
--- a/docs/reference/libedataserver/Makefile.am
+++ b/docs/reference/libedataserver/Makefile.am
@@ -4,6 +4,8 @@ DOC_MODULE = libedataserver
 # The top-level SGML file.
 DOC_MAIN_SGML_FILE = libedataserver-docs.sgml
 
+MKDB_OPTIONS = --sgml-mode --output-format=xml --name-space=e
+
 # Extra options to supply to gtkdoc-scan
 SCAN_OPTIONS = --deprecated-guards="EDS_DISABLE_DEPRECATED"
 
diff --git a/docs/reference/libedataserver/libedataserver-sections.txt b/docs/reference/libedataserver/libedataserver-sections.txt
index c395cd5..15cce5d 100644
--- a/docs/reference/libedataserver/libedataserver-sections.txt
+++ b/docs/reference/libedataserver/libedataserver-sections.txt
@@ -219,6 +219,8 @@ e_operation_pool_push
 EPhoneNumber
 EPhoneNumberError
 EPhoneNumberFormat
+EPhoneNumberMatch
+e_phone_number_is_supported
 e_phone_number_from_string
 e_phone_number_to_string
 e_phone_number_compare
diff --git a/libedataserver/e-phone-utils.h b/libedataserver/e-phone-utils.h
index 1ee9f39..e887c4f 100644
--- a/libedataserver/e-phone-utils.h
+++ b/libedataserver/e-phone-utils.h
@@ -72,6 +72,59 @@ typedef enum {
  * 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.
+ *
+ * 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
+ * "5423789" gives E_PHONE_NUMBER_MATCH_SHORT. For more detail have a look at
+ * the following table:
+ *
+ * <informaltable border="1" align="center">
+ *  <colgroup>
+ *   <col width="20%" />
+ *   <col width="20%" />
+ *   <col width="20%" />
+ *   <col width="20%" />
+ *   <col width="20%" />
+ *  </colgroup>
+ *  <tbody>
+ *   <tr>
+ *    <th></th>
+ *    <th align="center">+1-617-5423789</th>
+ *    <th align="center">+1-221-5423789</th>
+ *    <th align="center">221-5423789</th>
+ *    <th align="center">5423789</th>
+ *   </tr><tr>
+ *    <th align="right">+1-617-5423789</th>
+ *    <td align="center">exact</td>
+ *    <td align="center">none</td>
+ *    <td align="center">none</td>
+ *    <td align="center">short</td>
+ *   </tr><tr>
+ *    <th align="right">+1-221-5423789</th>
+ *    <td align="center">none</td>
+ *    <td align="center">exact</td>
+ *    <td align="center">national</td>
+ *    <td align="center">short</td>
+ *   </tr><tr>
+ *    <th align="right">221-5423789</th>
+ *    <td align="center">none</td>
+ *    <td align="center">national</td>
+ *    <td align="center">national</td>
+ *    <td align="center">short</td>
+ *   </tr><tr>
+ *    <th align="right">5423789</th>
+ *    <td align="center">short</td>
+ *    <td align="center">short</td>
+ *    <td align="center">short</td>
+ *    <td align="center">short</td>
+ *   </tr>
+ *  </tbody>
+ * </informaltable>
  */
 typedef enum {
 	E_PHONE_NUMBER_MATCH_NONE,
@@ -139,9 +192,10 @@ gboolean		e_phone_number_is_supported	(void) G_GNUC_CONST;
  * region.
  *
  * The 2-letter country code passed in @country_code only is used if the
- * @phone_number is not written in international format. If the number is
- * guaranteed to start with a '+' followed by the country calling code,
- * then "ZZ" can be passed here.
+ * @phone_number is not written in international format. The applications's
+ * currently locale is consulted if %NULL gets passed for @country_code.
+ * If the number is guaranteed to start with a '+' followed by the country
+ * calling code, then "ZZ" can be passed here.
  *
  * Returns: (transfer full): a new EPhoneNumber instance on success,
  * or %NULL on error. Call e_phone_number_free() to release this instance.