Improve documentation for star parameters

[kevinoid]

Is your feature request related to a problem? Please describe.

It is not clear to me how to document a star parameter of a variadic function and whether the parameter name should be prefixed with *, \*, or nothing. This is particularly true in Sphinx style, but also applies to Google and NumPy styles to some extent (*args and **kwargs appear in an example, but it's not clear if that's the preferred or only syntax). This has caused confusion for linters, such as:

• False positive for RST213 and RST210 from *arg and **kwargs peterjc/flake8-rst-docstrings#18
• *args is considered as missing in documentation pylint-dev/pylint#3733
• [v2.12 Regression] Asterisk argument mising-param-doc vs anomalous-backslash-in-string pylint-dev/pylint#5406

It appears that both no-prefix and backslash-star are accepted for Sphinx style, and that all three are accepted for Google and NumPy style (due to auto-escaping in sphinx.ext.napoleon as noted in peterjc/flake8-rst-docstrings#18 (comment) ). Is this correct? Are any styles preferred?

Describe the solution you'd like

I had checked for examples in both Describing code in Sphinx or The Python Domain. I'd recommend adding an example to both with the preferred style, and discussing other supported styles in The Python Domain.

Describe alternatives you've considered

Keeping the status quo is always an option. We can weigh the current ambiguity and confusion against the effort to write and maintain the docs.

Thanks for considering,
Kevin

[saroad2]

I would love to know the answer for that question.
This ability is very important in Pylint