Synchronize packaging docs with distutils’ (includes fix for #9302)

3 files changed, 42 insertions, 33 deletions

diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index 4c849a9..3adbc52 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -160,7 +160,7 @@ the full reference.
 .. class:: Extension
 
    The Extension class describes a single C or C++extension module in a setup
-   script. It accepts the following keyword arguments in its constructor
+   script. It accepts the following keyword arguments in its constructor:
 
    +------------------------+--------------------------------+---------------------------+
    | argument name          | value                          | type                      |
diff --git a/Doc/library/packaging.compiler.rst b/Doc/library/packaging.compiler.rst
index 38e9ce5..d771972 100644
--- a/Doc/library/packaging.compiler.rst
+++ b/Doc/library/packaging.compiler.rst
@@ -572,7 +572,7 @@ extension modules.
    the following keyword arguments in its constructor:
 
    +------------------------+--------------------------------+---------------------------+
-   | argument name          | value                          | type [#]_                 |
+   | argument name          | value                          | type                      |
    +========================+================================+===========================+
    | *name*                 | the full name of the           | string                    |
    |                        | extension, including any       |                           |
@@ -580,7 +580,7 @@ extension modules.
    |                        | filename or pathname, but      |                           |
    |                        | Python dotted name             |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *sources*              | list of source filenames,      | string                    |
+   | *sources*              | list of source filenames,      | list of strings           |
    |                        | relative to the distribution   |                           |
    |                        | root (where the setup script   |                           |
    |                        | lives), in Unix form (slash-   |                           |
@@ -593,12 +593,12 @@ extension modules.
    |                        | as source for a Python         |                           |
    |                        | extension.                     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *include_dirs*         | list of directories to search  | string                    |
+   | *include_dirs*         | list of directories to search  | list of strings           |
    |                        | for C/C++ header files (in     |                           |
    |                        | Unix form for portability)     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *define_macros*        | list of macros to define; each | (string, string) tuple or |
-   |                        | macro is defined using a       | (name, ``None``)          |
+   | *define_macros*        | list of macros to define; each | list of tuples            |
+   |                        | macro is defined using a       |                           |
    |                        | 2-tuple ``(name, value)``,     |                           |
    |                        | where *value* is               |                           |
    |                        | either the string to define it |                           |
@@ -609,31 +609,31 @@ extension modules.
    |                        | on Unix C compiler command     |                           |
    |                        | line)                          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *undef_macros*         | list of macros to undefine     | string                    |
+   | *undef_macros*         | list of macros to undefine     | list of strings           |
    |                        | explicitly                     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *library_dirs*         | list of directories to search  | string                    |
+   | *library_dirs*         | list of directories to search  | list of strings           |
    |                        | for C/C++ libraries at link    |                           |
    |                        | time                           |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *libraries*            | list of library names (not     | string                    |
+   | *libraries*            | list of library names (not     | list of strings           |
    |                        | filenames or paths) to link    |                           |
    |                        | against                        |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *runtime_library_dirs* | list of directories to search  | string                    |
+   | *runtime_library_dirs* | list of directories to search  | list of strings           |
    |                        | for C/C++ libraries at run     |                           |
    |                        | time (for shared extensions,   |                           |
    |                        | this is when the extension is  |                           |
    |                        | loaded)                        |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_objects*        | list of extra files to link    | string                    |
+   | *extra_objects*        | list of extra files to link    | list of strings           |
    |                        | with (e.g. object files not    |                           |
    |                        | implied by 'sources', static   |                           |
    |                        | library that must be           |                           |
    |                        | explicitly specified, binary   |                           |
    |                        | resource files, etc.)          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_compile_args*   | any extra platform- and        | string                    |
+   | *extra_compile_args*   | any extra platform- and        | list of strings           |
    |                        | compiler-specific information  |                           |
    |                        | to use when compiling the      |                           |
    |                        | source files in 'sources'. For |                           |
@@ -644,7 +644,7 @@ extension modules.
    |                        | for other platforms it could   |                           |
    |                        | be anything.                   |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_link_args*      | any extra platform- and        | string                    |
+   | *extra_link_args*      | any extra platform- and        | list of strings           |
    |                        | compiler-specific information  |                           |
    |                        | to use when linking object     |                           |
    |                        | files together to create the   |                           |
@@ -653,7 +653,7 @@ extension modules.
    |                        | Similar interpretation as for  |                           |
    |                        | 'extra_compile_args'.          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *export_symbols*       | list of symbols to be exported | string                    |
+   | *export_symbols*       | list of symbols to be exported | list of strings           |
    |                        | from a shared extension. Not   |                           |
    |                        | used on all platforms, and not |                           |
    |                        | generally necessary for Python |                           |
@@ -661,7 +661,7 @@ extension modules.
    |                        | export exactly one symbol:     |                           |
    |                        | ``init`` + extension_name.     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *depends*              | list of files that the         | string                    |
+   | *depends*              | list of files that the         | list of strings           |
    |                        | extension depends on           |                           |
    +------------------------+--------------------------------+---------------------------+
    | *language*             | extension language (i.e.       | string                    |
@@ -670,5 +670,8 @@ extension modules.
    |                        | from the source extensions if  |                           |
    |                        | not provided.                  |                           |
    +------------------------+--------------------------------+---------------------------+
-
-.. [#] For values documented as lists, the given type is the type of each element.
+   | *optional*             | specifies that a build failure | boolean                   |
+   |                        | in the extension should not    |                           |
+   |                        | abort the build process, but   |                           |
+   |                        | simply skip the extension.     |                           |
+   +------------------------+--------------------------------+---------------------------+
diff --git a/Doc/library/packaging.dist.rst b/Doc/library/packaging.dist.rst
index 7184f7f..25cb62b 100644
--- a/Doc/library/packaging.dist.rst
+++ b/Doc/library/packaging.dist.rst
@@ -25,10 +25,11 @@ module distribution being built/packaged/distributed/installed.
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | argument name      | value                          | type                                                        |
    +====================+================================+=============================================================+
-   | *name*             | The name of the project        | string                                                      |
+   | *name*             | The name of the project        | a string                                                    |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *version*          | The version number of the      | See :mod:`packaging.version`                                |
-   |                    | release                        |                                                             |
+   | *version*          | The version number of the      | a string                                                    |
+   |                    | release; see                   |                                                             |
+   |                    | :mod:`packaging.version`       |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *summary*          | A single line describing the   | a string                                                    |
    |                    | project                        |                                                             |
@@ -45,14 +46,14 @@ module distribution being built/packaged/distributed/installed.
    |                    | maintainer, if different from  |                                                             |
    |                    | the author                     |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *maintainer_email* | The email address of the       |                                                             |
+   | *maintainer_email* | The email address of the       | a string                                                    |
    |                    | current maintainer, if         |                                                             |
    |                    | different from the author      |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *home_page*        | A URL for the proejct          | a URL                                                       |
+   | *home_page*        | A URL for the proejct          | a string                                                    |
    |                    | (homepage)                     |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *download_url*     | A URL to download the project  | a URL                                                       |
+   | *download_url*     | A URL to download the project  | a string                                                    |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *packages*         | A list of Python packages that | a list of strings                                           |
    |                    | packaging will manipulate      |                                                             |
@@ -63,14 +64,13 @@ module distribution being built/packaged/distributed/installed.
    | *scripts*          | A list of standalone scripts   | a list of strings                                           |
    |                    | to be built and installed      |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *ext_modules*      | A list of Python extensions to | A list of instances of                                      |
+   | *ext_modules*      | A list of Python extensions to | a list of instances of                                      |
    |                    | be built                       | :class:`packaging.compiler.extension.Extension`             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *classifiers*      | A list of categories for the   | The list of available                                       |
-   |                    | distribution                   | categorizations is available on `PyPI                       |
-   |                    |                                | <http://pypi.python.org/pypi?:action=list_classifiers>`_.   |
+   | *classifiers*      | A list of categories for the   | a list of strings; valid classifiers are listed on `PyPi    |
+   |                    | distribution                   | <http://pypi.python.org/pypi?:action=list_classifiers>`_.   |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *distclass*        | the :class:`Distribution`      | A subclass of                                               |
+   | *distclass*        | the :class:`Distribution`      | a subclass of                                               |
    |                    | class to use                   | :class:`packaging.dist.Distribution`                        |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *script_name*      | The name of the setup.py       | a string                                                    |
@@ -83,13 +83,19 @@ module distribution being built/packaged/distributed/installed.
    | *options*          | default options for the setup  | a string                                                    |
    |                    | script                         |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *license*          | The license for the            | a string; should be used when there is no suitable License  |
-   |                    | distribution                   | classifier, or to specify a classifier                      |
+   | *license*          | The license for the            | a string                                                    |
+   |                    | distribution; should be used   |                                                             |
+   |                    | when there is no suitable      |                                                             |
+   |                    | License classifier, or to      |                                                             |
+   |                    | refine a classifier            |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *keywords*         | Descriptive keywords           | a list of strings; used by catalogs                         |
+   | *keywords*         | Descriptive keywords; used by  | a list of strings or a comma-separated string               |
+   |                    | catalogs such as PyPI          |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *platforms*        | Platforms compatible with this | a list of strings; should be used when there is no          |
-   |                    | distribution                   | suitable Platform classifier                                |
+   | *platforms*        | Platforms compatible with this | a list of strings or a comma-separated string               |
+   |                    | distribution; should be used   |                                                             |
+   |                    | when there is no suitable      |                                                             |
+   |                    | Platform classifier            |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
    |                    | :class:`Command` subclasses    |                                                             |