It seems that the status quo is to not include docstrings in type stubs. The type stub PEP draft [1] and typeshed contributing guidelines [2] explicitly say 'Do not include docstrings'. If docstrings are not included in stubs, tools/editors wishing to prove documentation in hovers and completions would still have to evaluate the code of the actual module (which might be a C module) and do non-standard merging between docs in *.py and types in *.pyi. This will make these tools slower and more difficult to implement. In order to improve code editing I suggest to allow or encourage the inclusion of docstrings in type stubs, perhaps also specifying a standardized format. In TypeScript, for example, documentation is often included in stubs, and has a standardized format [3]. What are your thoughts on the subjects? (Discussion moved from the PEP issue tracker [4].) [1] https://github.com/srittau/type-stub-pep/blob/5291660/pep-9999.rst [2] https://github.com/python/typeshed/blob/4cd9a8e/CONTRIBUTING.md [3] https://github.com/Microsoft/tsdoc [4] https://github.com/srittau/type-stub-pep/issues/38