Suggest to use `_` prefix for stubs-only types (#1005)

1 files changed, 7 insertions, 3 deletions

diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst
index d5ad685..ae45670 100644
--- a/docs/source/stubs.rst
+++ b/docs/source/stubs.rst
@@ -577,19 +577,21 @@ public method for which a library does not provided a usable runtime type::
 
   from typing import Protocol
 
-  class Readable(Protocol):
+  class _Readable(Protocol):
       def read(self) -> str: ...
 
-  def get_reader() -> Readable: ...
+  def get_reader() -> _Readable: ...
 
 Structural Types
 ----------------
 
-As seen in the example with ``Readable`` in the previous section, a common use
+As seen in the example with ``_Readable`` in the previous section, a common use
 of stub-only objects is to model types that are best described by their
 structure. These objects are called protocols [#pep544]_, and it is encouraged
 to use them freely to describe simple structural types.
 
+It is `recommended <private-definitions>`_ to prefix stubs-only object names with ``_``.
+
 Incomplete Stubs
 ----------------
 
@@ -921,6 +923,8 @@ No::
         ...
     def to_int3(x: str) -> int: pass
 
+.. _private-definitions:
+
 Private Definitions
 -------------------