Improve documentation for star parameters

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:

• peterjc/flake8-rst-docstrings#18
• PyCQA/pylint#3733
• PyCQA/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 https://github.com/peterjc/flake8-rst-docstrings/issues/18#issuecomment-661040265 ). 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

Start with the linked “Describing code in Sphinx” and “The Python Domain” documentation pages, then review the related Sphinx and Napoleon examples and linked linter discussions. Establish which star-parameter forms are supported and preferred for Sphinx, Google, and NumPy styles. Done means both pages include clear examples and the Python Domain page explains the accepted alternatives.