add docstrings to the stubs for builtins

[DetachHead]

i know it's not the standard to use docstrings in stubs, however i think it makes sense to do so for the builtins since they are written in c, meaning there there's no other way to view the docs from your IDE unless the language server has specifically added functionality to source the docs from elsewhere (see DetachHead/basedpyright#160).

[hauntsaninja]

Previously discussed in #4881 (comment)

[DetachHead]

it looks like that issue is more broad, suggesting that all stubs should have docstrings. i agree that maintaining the docstrings for every first and third party package in the stubs would be a nightmare, so i think they should only be added to modules that are written in C.

apparently pylance has a script or something that automatically generates docs for the builtins. perhaps typeshed could do something similar

[JelleZijlstra]

I definitely see how docstrings are useful for IDEs and other consumers of typeshed, but I feel there is limited value in actually checking in the docstrings in this repo, since all we'd do is copy them over straight from CPython.

Suggestion: Build a tool like the one requested in python/mypy#17200 that can take typeshed stubs and uses runtime introspection to add docstrings. Then, any IDE or other tool that wants typeshed + docstrings can run this tool at build time.

Such a tool could even be hosted in the mypy or typeshed repo.

[srittau]

Closing as duplicate of #4881. No need to discuss this in two places.

[DetachHead]

@srittau many of these old issues don't seem to let non-collaborators comment on them.

[AlexWaygood]

@srittau many of these old issues don't seem to let non-collaborators comment on them.

That's strange. The issue isn't locked, and a non-collaborator commented in April

[srittau]

That's strange indeed. I just checked our moderation settings, and nothing is enabled. Maybe a temporary problem? Or something that Ctrl+F5 will help with?

[DetachHead]

i don't think so. this seems to be a problem with other old issues too. i first noticed it last year python/mypy#11958 (comment)

[DetachHead]

in basedpyright 1.13.0, we ship modified versions of the stubs with docstrings for all compiled builtins. they're generated using docify, which perhaps typeshed could make use of as well?

(i would comment on #4881 instead, but i still don't seem to be allowed to comment on old issues :/ )