pygame
Add docstrings to modules in typestubs
Pretty self explanatory PR title, adds docstings to typestub pyi files, so that editors can display useful information about modules on mouse hover for user convenience. These docstrings are picked up from __doc__ attribute of the modules.
~~PR also fixes a minor issue https://github.com/pygame/pygame/pull/2999 introduced, when hovering over pygame base module, editor displays irrelevant docstrings about the typestub file being a generated file (the "generated file" comment has been moved into a separate comment in this PR)~~ This has been fixed in another one of my PRs
Things to discuss
- [ ] Should all the typestub classes and functions get docstrings in typestubs too? While this would mean that text editors can display useful information on hover, it also means more maintenance effort because there would be 2 places to update doc strings on future changes. This sort of thing could be hard to automate with a script, but it is theoretically possible.
Good review suggestions, but in this PR I merely copied __doc__ of module objects into the typestubs, so __doc__ would need fixing first. Also I'm still not sure whether we want to go this way, because this way can add a bit more maintenance, so we need to discuss this PR and any other possible alternatives first
PyCharm already picks up the existing documentation on hover btw.
So I'm not sure which code editor these changes are helping, but I wouldn't spend ages doubling up documentation if it is only helping a small fraction of users.
Well this PR was intended to fix the doc strings that you get when you hover over modules, on VS Code.
I'm not really sure how to proceed on this PR, because at the moment it just adds doc repetition which is not ideal from a maintenance POV. Maybe this is something to be fixed upstream in one of the editor tools.
Till then let this PR be a draft
Thanks for the approval
Hmmm... might try to come up with a little script to automate this