bpo-37800: Clean up importlib documentation for some module attributes

Doc/library/importlib.rst

@@ -420,30 +420,29 @@ ABC hierarchy::
         reloaded):
 
         - :attr:`__name__`
-            The name of the module.
+            The module's fully-qualified name.
 
         - :attr:`__file__`
-            The path to where the module data is stored (not set for built-in
-            modules).
+            The location from which the module was loaded (usually the path).
+            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 path to a compiled version of the code.
+            It is not set when the attribute would be inappropriate.
 
         - :attr:`__path__`
-            A list of strings specifying the search path within a
-            package. This attribute is not set on modules.
+            For packages, the list of strings specifying where to look for submodules.
+            This is used in the same way as :attr:`sys.path`, but just for the package.
+            Effectively, it is the indicator that the module is a package.  For
+            non-package modules, it is not set.
 
         - :attr:`__package__`
-            The parent package for the module/package. If the module is
-            top-level then it has a value of the empty string. The
-            :func:`importlib.util.module_for_loader` decorator can handle the
-            details for :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__`.
 
         - :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 loader that was used when loading the module.
 
         When :meth:`exec_module` is available then backwards-compatible
         functionality is provided.
@@ -1282,68 +1281,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
-   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``.
+   attribute available directly on the module object. For example,
+   ``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.  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.  Finders should always set this to a
+   non-empty (identifier) string.  The import system may set this to ``None``
+   in a few special cases.
 
    .. attribute:: loader
 
-   (``__loader__``)
+   (:attr:`__loader__`)
 
-   The loader to use for loading.  For namespace packages this should be
-   set to ``None``.
+   The :class:`Loader <importlib.abc.Loader>` that should be used when
+   loading the module.  Finders should always set this.
 
    .. 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 name of where the module should be loaded from (e.g. ``'builtin'``
+   for built-in modules and the path for modules loaded from source).
+   Finders should normally set this attribute, but it may be ``None`` (the
+   default) which indicates it is unspecified (like for namespace packages).
 
    .. attribute:: submodule_search_locations
 
-   (``__path__``)
+   (:attr:`__path__`)
 
-   List of strings for where to find submodules, if a package (``None``
-   otherwise).
+   For packages, the Finder must set this to the iterable specifying the
+   locations where submodules may be found for the package, even if
+   it's just an empty list.
+   For non-package modules, this should be set to ``None``.
+   For namespace packages (where :attr:`origin` is ``None``), this
+   is set automatically.
 
    .. attribute:: loader_state
 
-   Container of extra module-specific data for use during loading (or
-   ``None``).
+   The Finder may set this 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``).
+   Where a compiled version of the code should be stored (or ``None``).
+   This is typically a filename as provided by
+   ::func::`importlib.util.cache_from_source`.
 
    .. attribute:: parent
 
-   (``__package__``)
+   (:attr:`__package__`)
 
-   (Read-only) Fully-qualified name of the package to which the module
-   belongs as a submodule (or ``None``).
+   (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__`.
 
    .. 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
 ---------------------------------------------------
@@ -1435,8 +1446,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