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: ``"INTERNATIONAL"`` (`E.123
+<https://en.wikipedia.org/wiki/E.123#Telephone_number>`_) or ``"RFC3966"``.

docs/reference.rst

@@ -355,6 +355,15 @@ Validates:
 Settings
 ========
 
+.. warning::
+
+    By default, the library uses `the international public telecommunication
+    numbering plan E.164 <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 either `"INTERNATIONAL"` or
+    `"RFC3966"` to handle phone numbers extensions.
+
 .. setting:: PHONENUMBER_DB_FORMAT
 
 ``PHONENUMBER_DB_FORMAT``
@@ -367,19 +376,11 @@ Default: ``"E164"``.
 Choices:
 
 - ``"E164"`` (public international numbers),
-- ``"INTERNATIONAL"`` (international numbers, possibly with phone extensions),
+- ``"INTERNATIONAL"`` (international numbers, possibly with phone extensions,
+  `E.123 <https://en.wikipedia.org/wiki/E.123#Telephone_number>`_),
 - ``"RFC3966"`` (international numbers, possibly with phone extensions),
 - ``"NATIONAL"`` (discouraged, requires :setting:`PHONENUMBER_DEFAULT_REGION`).
 
-.. 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``.
 
 .. setting:: PHONENUMBER_DEFAULT_FORMAT
 
@@ -396,3 +397,13 @@ Choices:
 - ``"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``.