Welcome to FreeSimpleGUI Discussions!

[spyoungtech]

👋 Welcome!

We’re using Discussions as a place to connect with other members of our community. We hope that you:

• Ask questions you’re wondering about.
• Share ideas.
• Engage with other community members.
• Welcome others and are open-minded.

To get started, feel free to open new discussions on whatever you wish to discuss about FreeSimpleGUI!

[armstjc]

https://github.com/pandas-dev/pandas/blob/main/pandas/core/frame.py#L505

Would you support re-writing all function Docstrings to more resemble the function Docstrings format seen in packages such as pandas?

[spyoungtech]

Hmm. I'm not necessarily opposed to it. Is there a particular reason you would want docstrings in this particular format or why the current docstring format is not sufficient? Personally, I'm most familiar with the existing sphinx-style docstrings and would prefer that, but I am open to other options.

The most important thing to me is that they can be used with tools like sphinx for autogeneration of documentation (which I'm certain pandas makes use of, so that's not a major concern).

But something that probably has to be considered when thinking about changing the docstring style is that the project currently has a customized documentation generator which we inherited from PySimpleGUI. I want to remove this unnecessary complexity and make better use of standard documentation generation tools like sphinx autodoc (or similar) instead (I was also hoping to convert the existing parameter types from docstrings to type hints and let the documentation generation tool use those type hints, ideally). I don't think there's anything too crazy there; I think the original PySimpleGUI authors just weren't familiar with using autodoc tools, so I don't think it will be terribly difficult to deal with this situation.

[armstjc]

Few things:

1. Most of the docstrings look like this when viewed "as-is" or through a code editor like VS Code.
   
   

2. A lot of docstrings lack basic formatting and/or have unclear descriptors

3. In virtually all docstrings in PSG/FSG, none of the docstirngs show a newbie user how a function is supposed to be used at all, leading to confusion.

If FSG moves to a docstirng format similar to pandas, you could then use a documentation website generator such as pdoc, while having the benefit of any generated webpages being indistinguishable from the docstring that something like VS Code would show.

Here's an example from a project I've worked on:
https://armstjc.github.io/cfbd-json-py/cfbd_json_py/stats.html

[armstjc]

In addition, functions in FSG lack PEP 484 return type hints, outside of 3 instances:

• FreeSimpleGUI.Radio().get()
• FreeSimpleGUI.Listbox().get_list_values()
• FreeSimpleGUI.Checkbox().get_list_values()

https://peps.python.org/pep-0484/

[spyoungtech]

Most of the docstrings look like this when viewed "as-is" or through a code editor like VS Code.

Interesting. Though, I'm not 100% sure what expected behavior or VSCode functionality you're looking for here though. Can you elaborate on this or show me a 'working' example in VSCode? I use PyCharm, which does correctly parse the docstring parameters/types, if that's what you mean.

Maybe there's a plugin or something for that in VSCode? I'm not sure since I'm not a VSCode user.

A lot of docstrings lack basic formatting and/or have unclear descriptors [...]
none of the docstirngs show a newbie user how a function is supposed to be used

Agreed, many of the docstrings could be greatly improved in these ways. Though, I'm not sure that's necessarily dependent on using a particular docstring format.

PEP 484

Yeah, this is a big pain for me, too. And many of the declared types are wrong and there's a comically large number of typing errors against the types that are defined (for example, a parameter typed to int which has an incompatible default of None).

My ideal goal would be to be fully type hinted and PEP 561 compliant and get everything to point where mypy --strict passes, but there's a lot of work to be done to achieve this. I've started breaking out some of the components into individual modules so adding these type hints and mypy checks should hopefully be possible incrementally module by module.