Issue #15502: Bring the importlib.PathFinder docs and docstring more in line...

Issue #15502: Bring the importlib.PathFinder docs and docstring more in line with the new import system documentation, and fix various parts of the new docs that weren't quite right given PEP 420 or were otherwise a bit misleading. Also note the key terminology problem still being discussed in the issue

Doc/library/importlib.rst

@@ -606,7 +606,7 @@ find and load modules.
 .. class:: WindowsRegistryFinder
 
    :term:`Finder` for modules declared in the Windows registry.  This class
-   implements the :class:`importlib.abc.MetaPathFinder` ABC.
+   implements the :class:`importlib.abc.Finder` ABC.
 
    Only class methods are defined by this class to alleviate the need for
    instantiation.
@@ -616,14 +616,8 @@ find and load modules.
 
 .. class:: PathFinder
 
-    :term:`Finder` for :data:`sys.path`. This class implements the
-    :class:`importlib.abc.MetaPathFinder` ABC.
-
-    This class does not perfectly mirror the semantics of :keyword:`import` in
-    terms of :data:`sys.path`. No implicit path hooks are assumed for
-    simplification of the class and its semantics. This implies that when
-    ``None`` is found in :data:`sys.path_importer_cache` that it is simply
-    ignored instead of implying a default finder.
+    :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes.
+    This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
 
     Only class methods are defined by this class to alleviate the need for
     instantiation.
@@ -639,7 +633,8 @@ find and load modules.
         :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
         searched for a finder for the path entry and, if found, is stored in
         :data:`sys.path_importer_cache` along with being queried about the
-        module. If no finder is ever found then ``None`` is returned.
+        module. If no finder is ever found then ``None`` is both stored in
+        the cache and returned.
 
 
 .. class:: FileFinder(path, \*loader_details)

Lib/importlib/_bootstrap.py

@@ -1183,7 +1183,7 @@ class NamespaceLoader:
 
 class PathFinder:
 
-    """Meta path finder for sys.(path|path_hooks|path_importer_cache)."""
+    """Meta path finder for sys.path and package __path__ attributes."""
 
     @classmethod
     def _path_hooks(cls, path):
@@ -1204,10 +1204,10 @@ class PathFinder:
 
     @classmethod
     def _path_importer_cache(cls, path):
-        """Get the finder for the path from sys.path_importer_cache.
+        """Get the finder for the path entry from sys.path_importer_cache.
 
-        If the path is not in the cache, find the appropriate finder and cache
-        it. If no finder is available, store None.
+        If the path entry is not in the cache, find the appropriate finder
+        and cache it. If no finder is available, store None.
 
         """
         if path == '':