Endorsing putting docstrings in stub files is an intriguing idea, but I can see some potential issues with the approach:
From pep 484, the use-cases listed for stub files are:
- Extension modules
- Third-party modules whose authors have not yet added type hints
- Standard library modules for which type hints have not yet been
written
- Modules that must be compatible with Python 2 and 3
- Modules that use annotations for other purposes
Additionally, the pep mentions that stub files are
"only for use by
the type checker, not at runtime"
--
Obviously these things could change, or be changed, but taking the current wording, I can see a few issues with trying to promote docstrings in stub files:
1. Arguably(?), The official way to get a docstring from an object is to call `inspect.getdoc()`, so if we want official support for docstrings in stubs, inspect.getdoc() would have to be able to load and query stub files for docstrings at "runtime".
2. At the very least we'd need a standard library way to extract docstrings from objects that includes doing so from stub files, ending up with many different implementations of stub loading/docstring extracting withing different projects would not be ideal.
3. The use-cases listed above (from pep 484) suggest that stubs are really a workaround for cases where type information can't be provided directly in the source code. It's not super obvious that these use cases apply to docstrings. Extension modules already can provide docstrings directly, and documenting third-party modules seems a little unlikely (happy to be wrong about this!)
4. Promoting stub files from technical 'workaround', to being recommended in non-workaround situations seems like a
So, I think the above would need to be discussed/have some consensus as part of the debate.
Personally, this isn't a change I'd directly support, but have no major opinions either way.
Steve