Add comments about accidental virtual namespaces

1 files changed, 9 insertions, 1 deletions

diff --git a/setuptools/command/editable_wheel.py b/setuptools/command/editable_wheel.py
index c4b7ff9e..ccd0e60e 100644
--- a/setuptools/command/editable_wheel.py
+++ b/setuptools/command/editable_wheel.py
@@ -585,7 +585,14 @@ def _absolute_root(path: _Path) -> str:
 def _find_virtual_namespaces(pkg_roots: Dict[str, str]) -> Iterator[str]:
     """By carefully designing ``package_dir``, it is possible to implement the logical
     structure of PEP 420 in a package without the corresponding directories.
-    This function will try to find this kind of namespaces.
+
+    Moreover a parent package can be purposefully/accidentally skipped in the discovery
+    phase (e.g. ``find_packages(include=["mypkg.*"])``, when ``mypkg.foo`` is included
+    by ``mypkg`` itself is not).
+    We consider this case to also be a virtual namespace (ignoring the original
+    directory) to emulate a non-editable installation.
+
+    This function will try to find these kinds of namespaces.
     """
     for pkg in pkg_roots:
         if "." not in pkg:
@@ -595,6 +602,7 @@ def _find_virtual_namespaces(pkg_roots: Dict[str, str]) -> Iterator[str]:
             partial_name = ".".join(parts[:i])
             path = Path(find_package_path(partial_name, pkg_roots, ""))
             if not path.exists() or partial_name not in pkg_roots:
+                # partial_name not in pkg_roots ==> purposefully/accidentally skipped
                 yield partial_name