Do we need to add docstrings to the pyi files?

[Starbuck5]

I feel like I used to see docstrings in my dev environment (VS code), but I don't see them now.

All I see right now is the type information, for example:

If I go into event.pyi as a test and replace the ... with a docstring, it shows up:

def event_name(type: int, /) -> str: ...
def set_blocked(type: Optional[_EventTypes], /) -> None:
    """blocked blocked blocked blocked..."""
def set_allowed(type: Optional[_EventTypes], /) -> None: ...
def get_blocked(type: _EventTypes, /) -> bool: ...
def set_grab(grab: bool, /) -> None: ...

If I hover over pygame.event.set_blocked I now see this very insightful information:

This seems like a big win if we can solve this in a nice manner.

[ankith26]

I remember discussing this in previous issues (I'm not able to find any links RN)

Anyways, my take was that we can either

1. Make or use a tool that can copy the docs from code into the stubs
2. Update the tool being used by VS code to somehow pick up the docs from the implementation?

Basically, I don't want it to be a manually updated thing that adds developer burden

[Starbuck5]

There are lots of possibilities here.

• Our runtime docstrings are generated from the docs sl/sg attribute
• Docstrings could be more detailed by taking in information from the rest of the docs
• Do most editors render docstrings as markdown?
• We can use markdown instead of reST in our docs, should we?
• Different function signatures could be annotated differently to explain the args that are actually being used.
• We could generate docs from stubs and have the stubs be the universal source of truth, or vice versa. We could put a universal source of truth for stubs and docs in the code and have everything be generated off that.
• We could try to unify the method overloading in the stubs with the method overloading expressed in the documentation.
• Manual might not be so bad, the stubs are already manually written.

[ankith26]

We could generate docs from stubs and have the stubs be the universal source of truth, or vice versa. We could put a universal source of truth for stubs and docs in the code and have everything be generated off that.

Hmmm. I think I like the idea of not having separate .rst files for docs. We could have all docs as docstrings in the stubs, and generate docs from this. This will be a lot of manual porting/labour work, but it may pay well in the long run