[🚀 Feature]: Consistent docstring format for python bindings (Google vs reST)

[symonk]

Feature and motivation

Right now across the code base there are docstrings in different formats. A mix of:

Google style, i.e:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

and reST style:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

I personally prefer the restructured text versions myself, but I prefer consistency across the board of anything, any preference? Ideally we should have a linter of some sort (be it a tox recipe) that enforces new docstrings are adhering to this. I think it would be useful for building out a modern docs page in future with something like mkdocs & mkdocstrings.

There might even be a tool that is smart enough to parse our files and convert each of the above to the other types, I had a look and a few tools exist but seem to be in their infancy.

Opening this ticket so we can decide exactly what type we want to apply throughout collectively. Thanks

Usage example

N/A

I see this as a phase-1 in replacing our existing python API docs (they are very old and don't look particular nice). Once we have consistent style here we can look at auto generating a modern site with mkdocs (not to be confused with selenium.dev - this is more of an API reference for python specifics)

[symonk]

also in the examples above as we add more and more types, types are inferred correctly and there is no need to document them explicitly in the docstrings.

[symonk]

https://github.com/dadadel/pyment/ is a potential option to automate the process, tho it's not something I have used before - edit: not very well maintained as of recently it would appear

[olfMombach]

I second this. Also, as a motivation, when using mixed docstring formats in IDEs like PyCharm Intellisense can get confused and I noticed it failed to read parameter specifications for methods using the deviating style.

[github-actions[bot]]

This issue is stale because it has been open 280 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[titusfortner]

@symonk / @AutomatedTester did we decide what we want to do for this? Do we still have a mix of these in our repo?

[github-actions[bot]]

This issue is stale because it has been open 280 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[olfMombach]

Any update on this?

[github-actions[bot]]

This issue is stale because it has been open 280 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[selenium-ci]

This issue is looking for contributors.

Please comment below or reach out to us through our IRC/Slack/Matrix channels if you are interested.

[cgoldberg]

This is still relevant and contributions to making this consistent are welcomed.

[github-actions[bot]]

This issue is stale because it has been open 180 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[iampopovich]

@symonk / @AutomatedTester did we decide what we want to do for this? Do we still have a mix of these in our repo?

It's still not clear which style is considered preferable. I'll take over support if there's a definitive solution that satisfies everyone.

[cgoldberg]

I prefer Google-style docstrings, but I'm not sure what we currently use most. I think we use a mix of Google-style, reST-style, and a few styles people made up over the years. We do use some ruff rules for linting that enforce PEP257 docstring conventions, but AFAIK they don't cover this.

This is the guide for Google-style: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

[diemol]

@cgoldberg Since you work mostly with the Python bindings, I think we should follow your recommendation,

[iampopovich]

@cgoldberg may we reopen issue https://github.com/SeleniumHQ/selenium/issues/9480 many methods and classes have poor type hinting for input parameters and return types

[cgoldberg]

@iampopovich we've been tracking it in #15697, which is basically the same thing. There have been some recent improvements, but we're still not totally there yet.,

[cgoldberg]

This is all done, and we have ruff rules in place to ensure consistency going forward. See #16432

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity since it was closed. Please open a new issue for related bugs.