Add a note about modules that should not be included into stubs (#1019)

1 files changed, 13 insertions, 0 deletions

diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst
index 24987d4..a7ab6df 100644
--- a/docs/source/stubs.rst
+++ b/docs/source/stubs.rst
@@ -524,6 +524,17 @@ Type Stub Content
 This section documents best practices on what elements to include or
 leave out of type stubs.
 
+Modules excluded fom stubs
+--------------------------
+
+Not all modules should be included into stubs.
+
+It is recommended to exclude:
+
+1. Implementation details, with `multiprocessing/popen_spawn_win32.py <https://github.com/python/cpython/blob/main/Lib/multiprocessing/popen_spawn_win32.py>`_ as a notable example
+2. Modules that are not supposed to be imported, such as ``__main__.py``
+3. Protected modules that start with a single ``_`` char. However, when needed protected modules can still be added (see :ref:`undocumented-objects` section below)
+
 Public Interface
 ----------------
 
@@ -539,6 +550,8 @@ The following should always be included:
 Other objects may be included if they are not prefixed with an underscore
 or if they are being used in practice. (See the next section.)
 
+.. _undocumented-objects:
+
 Undocumented Objects
 --------------------