bpo-37800: Clean up importlib documentation for some module attributes (GH-10016)

Automerge-Triggered-By: GH:brettcannon

1 files changed, 77 insertions, 63 deletions

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 5b4fba3..6b71e64 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -383,11 +383,11 @@ ABC hierarchy::
     See :pep:`302` for the exact definition for a loader.
 
     Loaders that wish to support resource reading should implement a
-    ``get_resource_reader(fullname)`` method as specified by
+    :meth:`get_resource_reader` method as specified by
     :class:`importlib.abc.ResourceReader`.
 
     .. versionchanged:: 3.7
-       Introduced the optional ``get_resource_reader()`` method.
+       Introduced the optional :meth:`get_resource_reader` method.
 
     .. method:: create_module(spec)
 
@@ -405,17 +405,17 @@ ABC hierarchy::
 
        An abstract method that executes the module in its own namespace
        when a module is imported or reloaded.  The module should already
-       be initialized when ``exec_module()`` is called. When this method exists,
-       :meth:`~importlib.abc.Loader.create_module` must be defined.
+       be initialized when :meth:`exec_module` is called.  When this method exists,
+       :meth:`create_module` must be defined.
 
        .. versionadded:: 3.4
 
        .. versionchanged:: 3.6
-          :meth:`~importlib.abc.Loader.create_module` must also be defined.
+          :meth:`create_module` must also be defined.
 
     .. method:: load_module(fullname)
 
-        A legacy method for loading a module. If the module cannot be
+        A legacy method for loading a module.  If the module cannot be
         loaded, :exc:`ImportError` is raised, otherwise the loaded module is
         returned.
 
@@ -423,62 +423,64 @@ ABC hierarchy::
         module should be used and reloaded.
         Otherwise the loader should create a new module and insert it into
         :data:`sys.modules` before any loading begins, to prevent recursion
-        from the import. If the loader inserted a module and the load fails, it
+        from the import.  If the loader inserted a module and the load fails, it
         must be removed by the loader from :data:`sys.modules`; modules already
         in :data:`sys.modules` before the loader began execution should be left
         alone (see :func:`importlib.util.module_for_loader`).
 
-        The loader should set several attributes on the module.
-        (Note that some of these attributes can change when a module is
+        The loader should set several attributes on the module
+        (note that some of these attributes can change when a module is
         reloaded):
 
         - :attr:`__name__`
-            The name of the module.
+            The module's fully-qualified name.
+            It is ``'__main__'`` for an executed module.
 
         - :attr:`__file__`
-            The path to where the module data is stored (not set for built-in
-            modules).
+            The location the :term:`loader` used to load the module.
+            For example, for modules loaded from a .py file this is the filename.
+            It is not set on all modules (e.g. built-in modules).
 
         - :attr:`__cached__`
-            The path to where a compiled version of the module is/should be
-            stored (not set when the attribute would be inappropriate).
+            The filename of a compiled version of the module's code.
+            It is not set on all modules (e.g. built-in modules).
 
         - :attr:`__path__`
-            A list of strings specifying the search path within a
-            package. This attribute is not set on modules.
+            The list of locations where the package's submodules will be found.
+            Most of the time this is a single directory.
+            The import system passes this attribute to ``__import__()`` and to finders
+            in the same way as :attr:`sys.path` but just for the package.
+            It is not set on non-package modules so it can be used
+            as an indicator that the module is a package.
 
         - :attr:`__package__`
-            The fully-qualified name of the package under which the module was
-            loaded as a submodule (or the empty string for top-level modules).
-            For packages, it is the same as :attr:`__name__`.  The
-            :func:`importlib.util.module_for_loader` decorator can handle the
-            details for :attr:`__package__`.
+            The fully-qualified name of the package the module is in (or the
+            empty string for a top-level module).
+            If the module is a package then this is the same as :attr:`__name__`.
 
         - :attr:`__loader__`
-            The loader used to load the module. The
-            :func:`importlib.util.module_for_loader` decorator can handle the
-            details for :attr:`__package__`.
+            The :term:`loader` used to load the module.
 
         When :meth:`exec_module` is available then backwards-compatible
         functionality is provided.
 
         .. versionchanged:: 3.4
            Raise :exc:`ImportError` when called instead of
-           :exc:`NotImplementedError`. Functionality provided when
+           :exc:`NotImplementedError`.  Functionality provided when
            :meth:`exec_module` is available.
 
         .. deprecated:: 3.4
            The recommended API for loading a module is :meth:`exec_module`
-           (and :meth:`create_module`).  Loaders should implement
-           it instead of load_module().  The import machinery takes care of
-           all the other responsibilities of load_module() when exec_module()
-           is implemented.
+           (and :meth:`create_module`).  Loaders should implement it instead of
+           :meth:`load_module`.  The import machinery takes care of all the
+           other responsibilities of :meth:`load_module` when
+           :meth:`exec_module` is implemented.
 
     .. method:: module_repr(module)
 
-        A legacy method which when implemented calculates and returns the
-        given module's repr, as a string. The module type's default repr() will
-        use the result of this method as appropriate.
+        A legacy method which when implemented calculates and returns the given
+        module's representation, as a string.  The module type's default
+        :meth:`__repr__` will use the result of this method as appropriate.
 
         .. versionadded:: 3.3
 
@@ -1420,69 +1422,80 @@ find and load modules.
 .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
 
    A specification for a module's import-system-related state.  This is
-   typically exposed as the module's ``__spec__`` attribute.  In the
+   typically exposed as the module's :attr:`__spec__` attribute.  In the
    descriptions below, the names in parentheses give the corresponding
-   attribute available directly on the module object.
-   E.g. ``module.__spec__.origin == module.__file__``.  Note however that
+   attribute available directly on the module object,
+   e.g. ``module.__spec__.origin == module.__file__``.  Note, however, that
    while the *values* are usually equivalent, they can differ since there is
-   no synchronization between the two objects.  Thus it is possible to update
-   the module's ``__path__`` at runtime, and this will not be automatically
-   reflected in ``__spec__.submodule_search_locations``.
+   no synchronization between the two objects.  For example, it is possible to update
+   the module's :attr:`__file__` at runtime and this will not be automatically
+   reflected in the module's :attr:`__spec__.origin`, and vice versa.
 
    .. versionadded:: 3.4
 
    .. attribute:: name
 
-   (``__name__``)
+   (:attr:`__name__`)
 
-   A string for the fully-qualified name of the module.
+   The module's fully-qualified name.
+   The :term:`finder` should always set this attribute to a non-empty string.
 
    .. attribute:: loader
 
-   (``__loader__``)
+   (:attr:`__loader__`)
 
-   The :term:`Loader <loader>` that should be used when loading
-   the module.  :term:`Finders <finder>` should always set this.
+   The :term:`loader` used to load the module.
+   The :term:`finder` should always set this attribute.
 
    .. attribute:: origin
 
-   (``__file__``)
+   (:attr:`__file__`)
 
-   Name of the place from which the module is loaded, e.g. "builtin" for
-   built-in modules and the filename for modules loaded from source.
-   Normally "origin" should be set, but it may be ``None`` (the default)
-   which indicates it is unspecified (e.g. for namespace packages).
+   The location the :term:`loader` should use to load the module.
+   For example, for modules loaded from a .py file this is the filename.
+   The :term:`finder` should always set this attribute to a meaningful value
+   for the :term:`loader` to use.  In the uncommon case that there is not one
+   (like for namespace packages), it should be set to ``None``.
 
    .. attribute:: submodule_search_locations
 
-   (``__path__``)
+   (:attr:`__path__`)
 
-   List of strings for where to find submodules, if a package (``None``
-   otherwise).
+   The list of locations where the package's submodules will be found.
+   Most of the time this is a single directory.
+   The :term:`finder` should set this attribute to a list, even an empty one, to indicate
+   to the import system that the module is a package.  It should be set to ``None`` for
+   non-package modules.  It is set automatically later to a special object for
+   namespace packages.
 
    .. attribute:: loader_state
 
-   Container of extra module-specific data for use during loading (or
-   ``None``).
+   The :term:`finder` may set this attribute to an object containing additional,
+   module-specific data to use when loading the module.  Otherwise it should be
+   set to ``None``.
 
    .. attribute:: cached
 
-   (``__cached__``)
+   (:attr:`__cached__`)
 
-   String for where the compiled module should be stored (or ``None``).
+   The filename of a compiled version of the module's code.
+   The :term:`finder` should always set this attribute but it may be ``None``
+   for modules that do not need compiled code stored.
 
    .. attribute:: parent
 
-   (``__package__``)
+   (:attr:`__package__`)
 
-   (Read-only) The fully-qualified name of the package under which the module
-   should be loaded as a submodule (or the empty string for top-level modules).
-   For packages, it is the same as :attr:`__name__`.
+   (Read-only) The fully-qualified name of the package the module is in (or the
+   empty string for a top-level module).
+   If the module is a package then this is the same as :attr:`name`.
 
    .. attribute:: has_location
 
-   Boolean indicating whether or not the module's "origin"
-   attribute refers to a loadable location.
+   ``True`` if the spec's :attr:`origin` refers to a loadable location,
+    ``False`` otherwise.  This value impacts how :attr:`origin` is interpreted
+    and how the module's :attr:`__file__` is populated.
+
 
 :mod:`importlib.util` -- Utility code for importers
 ---------------------------------------------------
@@ -1574,8 +1587,9 @@ an :term:`importer`.
 
    :exc:`ImportError` is raised if **name** is a relative module name but
    **package** is a false value (e.g. ``None`` or the empty string).
-   :exc:`ImportError` is also raised a relative name would escape its containing
-   package (e.g. requesting ``..bacon`` from within the ``spam`` package).
+   :exc:`ImportError` is also raised if a relative name would escape its
+   containing package (e.g. requesting ``..bacon`` from within the ``spam``
+   package).
 
    .. versionadded:: 3.3