Document phone number extension handling

docs/index.rst

@@ -44,4 +44,5 @@ your ``settings.py`` file :external+django:setting:`INSTALLED_APPS`:
    :maxdepth: 2
    :caption: Contents:
 
+   phonenumbers
    reference

docs/phonenumbers.rst

@@ -0,0 +1,31 @@
+Handling phone numbers
+======================
+
+`Google’s libphonenumber “Falsehoods Programmers Believe About Phone Numbers”
+<https://github.com/google/libphonenumber/blob/master/FALSEHOODS.md>`_ are
+worth keeping in mind, especially since this library relies heavily on
+`libphonenumber <https://github.com/google/libphonenumber/>`_.
+
+About phone numbers extensions
+------------------------------
+
+An extension is an additional phone line added to an existing phone system,
+making it possible to reach a specific employee or department within an
+organization. An extension is defined in the following manner:
+
+.. doctest:: extensions
+
+   >>> import phonenumbers
+   >>> phonenumbers.parse("+1 604-401-1234 ext. 987")
+   PhoneNumber(country_code=1, national_number=6044011234, extension='987', italian_leading_zero=None, number_of_leading_zeros=None, country_code_source=0, preferred_domestic_carrier_code=None)
+   >>> phonenumbers.parse("+1 604-401-1234,987")
+   PhoneNumber(country_code=1, national_number=6044011234, extension='987', italian_leading_zero=None, number_of_leading_zeros=None, country_code_source=0, preferred_domestic_carrier_code=None)
+
+The library primarily focuses on public phone numbers, its default format and
+database representation are using `E.164
+<https://en.wikipedia.org/wiki/E.164>`_, which has no support for extensions.
+
+Projects that need to handle phone number extensions must set **both**
+:setting:`PHONENUMBER_DEFAULT_FORMAT` and :setting:`PHONENUMBER_DB_FORMAT` to
+an extension-compatible format, as described in
+:ref:`settings-format-choices`.

docs/reference.rst

@@ -355,31 +355,53 @@ Validates:
 Settings
 ========
 
+.. _settings-format-choices:
+
+Phone number format choices
+---------------------------
+
++------------------------+---------------+------------+-----------------------------------------------------------------+
+| Setting value          | International | Extensions | Notes                                                           |
++========================+===============+============+=================================================================+
+| ``"E164"`` *(default)* | ✓             | ❌         | https://en.wikipedia.org/wiki/E.164                             |
++------------------------+---------------+------------+-----------------------------------------------------------------+
+| ``"INTERNATIONAL"``    | ✓             | ✓          | https://en.wikipedia.org/wiki/E.123#Telephone_number            |
++------------------------+---------------+------------+-----------------------------------------------------------------+
+| ``"RFC3966"``          | ✓             | ✓          | https://www.rfc-editor.org/rfc/rfc3966.html                     |
++------------------------+---------------+------------+-----------------------------------------------------------------+
+| ``"NATIONAL"``         | ❌            | ✓          | **DISCOURAGED**, requires :setting:`PHONENUMBER_DEFAULT_REGION` |
++------------------------+---------------+------------+-----------------------------------------------------------------+
+
+.. warning::
+
+    By default, the library uses `E.164, the international public
+    telecommunication numbering plan <https://en.wikipedia.org/wiki/E.164>`_,
+    which **does not support phone numbers extensions**. Set **both**
+    :setting:`PHONENUMBER_DB_FORMAT` and :setting:`PHONENUMBER_DEFAULT_FORMAT`
+    to an extension-compatible format to handle phone numbers extensions.
+
 .. setting:: PHONENUMBER_DB_FORMAT
 
 ``PHONENUMBER_DB_FORMAT``
 -------------------------
 
-Store phone numbers strings in the specified format.
+Store phone numbers strings in the specified format in the database.
 
 Default: ``"E164"``.
 
-Choices:
+See :ref:`settings-format-choices`.
 
-- ``"E164"`` (public international numbers),
-- ``"INTERNATIONAL"`` (international numbers, possibly with phone extensions),
-- ``"RFC3966"`` (international numbers, possibly with phone extensions),
-- ``"NATIONAL"`` (discouraged, requires :setting:`PHONENUMBER_DEFAULT_REGION`).
+.. warning:: **Data loss may occur when changing the DB format.**
 
-.. setting:: PHONENUMBER_DEFAULT_REGION
+   Phone numbers stored in the database are parsed every time they are loaded
+   from the database.
 
-``PHONENUMBER_DEFAULT_REGION``
-------------------------------
+   When switching from a format that can represent extensions to a format that
+   cannot, the **extension information is definitely lost**.
 
-`ISO-3166-1 <https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes>`_
-two-letter country code indicating how to interpret regional phone numbers.
-
-Default: ``None``.
+   When using :setting:`PHONENUMBER_DB_FORMAT`\ ``="NATIONAL"``, changing the
+   :setting:`PHONENUMBER_DEFAULT_REGION` will cause phone numbers stored in the
+   database to be interpreted differently, resulting in data corruption.
 
 .. setting:: PHONENUMBER_DEFAULT_FORMAT
 
@@ -390,9 +412,14 @@ String formatting of phone numbers.
 
 Default: ``"E164"``.
 
-Choices:
+See :ref:`settings-format-choices`.
 
-- ``"E164"`` (no support of phone extensions),
-- ``"INTERNATIONAL"``,
-- ``"RFC3966"``,
-- ``"NATIONAL"`` (discouraged, fails to represent international phone numbers).
+.. setting:: PHONENUMBER_DEFAULT_REGION
+
+``PHONENUMBER_DEFAULT_REGION``
+------------------------------
+
+`ISO-3166-1 <https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes>`_
+two-letter country code indicating how to interpret regional phone numbers.
+
+Default: ``None``.