3 files changed, 56 insertions, 19 deletions
diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst
index 06d300547d..aafa3d89d0 100644
--- a/Doc/extending/building.rst
+++ b/Doc/extending/building.rst
@@ -1,27 +1,58 @@
 .. highlightlang:: c
 
-
 .. _building:
 
-********************************************
-Building C and C++ Extensions with distutils
-********************************************
+*****************************
+Building C and C++ Extensions
+*****************************
 
-.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
+``.pyd`` on Windows), which exports an *initialization function*.
+
+To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
+and must be named after the module name, with an appropriate extension.
+When using distutils, the correct filename is generated automatically.
+
+The initialization function has the signature:
+
+.. c:function:: PyObject* PyInit_modulename(void)
+
+It returns either a fully-initialized module, or a :c:type:`PyModuleDef`
+instance. See :ref:`initializing-modules` for details.
+
+.. highlightlang:: python
 
+For modules with ASCII-only names, the function must be named
+``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
+module. When using :ref:`multi-phase-initialization`, non-ASCII module names
+are allowed. In this case, the initialization function name is
+``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
+*punycode* encoding with hyphens replaced by underscores. In Python::
 
-Starting in Python 1.4, Python provides, on Unix, a special make file for
-building make files for building dynamically-linked extensions and custom
-interpreters.  Starting with Python 2.0, this mechanism (known as related to
-Makefile.pre.in, and Setup files) is no longer supported. Building custom
-interpreters was rarely used, and extension modules can be built using
-distutils.
+    def initfunc_name(name):
+        try:
+            suffix = b'_' + name.encode('ascii')
+        except UnicodeEncodeError:
+            suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
+        return b'PyInit' + suffix
+
+It is possible to export multiple modules from a single shared library by
+defining multiple initialization functions. However, importing them requires
+using symbolic links or a custom importer, because by default only the
+function corresponding to the filename is found.
+See :PEP:`489#multiple-modules-in-one-library` for details.
+
+
+.. highlightlang:: c
+
+Building C and C++ Extensions with distutils
+============================================
+
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
 
-Building an extension module using distutils requires that distutils is
-installed on the build machine, which is included in Python 2.x and available
-separately for Python 1.5. Since distutils also supports creation of binary
-packages, users don't necessarily need a compiler and distutils to install the
-extension.
+Extension modules can be built using distutils,  which is included in Python.
+Since distutils also supports creation of binary packages, users don't
+necessarily need a compiler and distutils to install the extension.
 
 A distutils package contains a driver script, :file:`setup.py`. This is a plain
 Python file, which, in the most simple case, could look like this::
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index a83fb6e579..8cc41840d7 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -413,6 +413,13 @@ A more substantial example module is included in the Python source distribution
 as :file:`Modules/xxmodule.c`.  This file may be used as a  template or simply
 read as an example.
 
+.. note::
+
+   Unlike our ``spam`` example, ``xxmodule`` uses *multi-phase initialization*
+   (new in Python 3.5), where a PyModuleDef structure is returned from
+   ``PyInit_spam``, and creation of the module is left to the import machinery.
+   For details on multi-phase initialization, see :PEP:`489`.
+
 
 .. _compilation:
 
diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst
index 3fd5e576de..f0c69b851e 100644
--- a/Doc/extending/windows.rst
+++ b/Doc/extending/windows.rst
@@ -98,9 +98,8 @@ described here are distributed with the Python sources in the
    it.  Copy your C sources into it.  Note that the module source file name does
    not necessarily have to match the module name, but the name of the
    initialization function should match the module name --- you can only import a
-   module :mod:`spam` if its initialization function is called :c:func:`initspam`,
-   and it should call :c:func:`Py_InitModule` with the string ``"spam"`` as its
-   first argument (use the minimal :file:`example.c` in this directory as a guide).
+   module :mod:`spam` if its initialization function is called :c:func:`PyInit_spam`,
+   (see :ref:`building`, or use the minimal :file:`Modules/xxmodule.c` as a guide).
    By convention, it lives in a file called :file:`spam.c` or :file:`spammodule.c`.
    The output file should be called :file:`spam.pyd` (in Release mode) or
    :file:`spam_d.pyd` (in Debug mode). The extension :file:`.pyd` was chosen