Many Python developers rely heavily on docstrings for interactive feedback
during coding. Docstrings are consumed by language servers like
[Pylance](https://github.com/microsoft/pylance-release) and
[Pyright](https://github.com/microsoft/pyright) for completion suggestions,
signature help (when typing arguments for a function call), and hover text
(when the mouse pointer hovers over a symbol).
I can't speak for all Python language servers and smart editors, but Pylance
and Pyright utilize docstrings found in stub files. If a stub file doesn't
contain docstrings for a symbol, these tools attempt to locate the
corresponding symbol in the Python source (".py") file and use any docstring
found there. Finding the corresponding symbol in the source is sometimes
difficult or impossible because stubs often have a different file layout than
the corresponding source files, but these tools employ various heuristics that
work in many cases. It's still somewhat hit or miss, so if we're going to talk
about standardizing this, I'd want to encourage us to find a mechanism that is
deterministic.
If a symbol is implemented in another language (e.g. a Cython compiled binary),
there is nowhere for a static analysis tool to find docstrings other than the
type stub. We therefore encourage stub authors to include docstrings in their
stubs if there is no corresponding source file.
I'd assert that docstrings are way more important and useful for static
analysis tools than they are for any dynamic (runtime) use cases, but maybe
there are some runtime uses that I'm not considering. Language servers need to
use static techniques because it is not safe (nor is it sufficiently
performant) to load and execute Python source at edit time without the
developer's knowledge just to extract docstrings.
On a related topic, we should also discuss the practice of replacing default
parameter values in stubs with "...". In cases where the type stub is the only
source of truth for a language server, it would be valuable to preserve the
default parameter values so they can be displayed in context as the developer
is typing. Otherwise, they see "..." and don't know what default value to
expect.
-Eric
---
Eric Traut
Contributor to Pylance and Pyright
Microsoft Corp.
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/5NARCV2CW32UUHQPHL7YIS5QEMIRKJBY/
Code of Conduct: http://python.org/psf/codeofconduct/
