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
Please, no. Keeping the docstrings in sync with the original code's docstrings would be much more work than keeping just the signatures in sync. Typeshed is not intended to serve as a redundant repository for docstrings for editors that are too lazy to dig up the real docstrings. On Wed, Apr 17, 2019 at 11:55 AM Matan Gover <matangover@gmail.com> wrote:
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 _______________________________________________ Typing-sig mailing list -- typing-sig@python.org To unsubscribe send an email to typing-sig-leave@python.org https://mail.python.org/mailman3/lists/typing-sig.python.org/
-- --Guido van Rossum (python.org/~guido) *Pronouns: he/him/his **(why is my pronoun here?)* <http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-c...>
I agree with your concerns. Typeshed authors don't want this burden, they are concerned with type checking only. But why discourage PEP 561 stub authors from including docs if they want to? If PEP 561 stubs would be allowed to include docstrings, and somebody would take the burden of maintaining a 'docshed', editors could provide adequate docs. Maintaining 'docshed' separately from typeshed could lead to even more redundancy, but seems like it's the only option. In the absence of 'docshed', editors must analyze all of the code's library dependencies. Some editors have implemented this but the analysis is error-prone and slow -- re-analyzing stdlib and third party packages for every venv. The purpose of my suggestion is to be able to circumvent this analysis.
Maybe you can focus on tooling to automate the process then. On Wed, Apr 17, 2019 at 1:26 PM Matan Gover <matangover@gmail.com> wrote:
I agree with your concerns. Typeshed authors don't want this burden, they are concerned with type checking only. But why discourage PEP 561 stub authors from including docs if they want to?
If PEP 561 stubs would be allowed to include docstrings, and somebody would take the burden of maintaining a 'docshed', editors could provide adequate docs. Maintaining 'docshed' separately from typeshed could lead to even more redundancy, but seems like it's the only option.
In the absence of 'docshed', editors must analyze all of the code's library dependencies. Some editors have implemented this but the analysis is error-prone and slow -- re-analyzing stdlib and third party packages for every venv. The purpose of my suggestion is to be able to circumvent this analysis. _______________________________________________ Typing-sig mailing list -- typing-sig@python.org To unsubscribe send an email to typing-sig-leave@python.org https://mail.python.org/mailman3/lists/typing-sig.python.org/
-- --Guido van Rossum (python.org/~guido) *Pronouns: he/him/his **(why is my pronoun here?)* <http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-c...>
participants (2)
-
Guido van Rossum -
Matan Gover