Sorry for the late reply—this fell through the cracks.
Yes, indeed—it could be part of our existing Style Guide, as @ezio-melotti mentioned (especially since it should get its own page soon, following the reorganization). The focus would be on giving doc writers an easy to follow structure and helpful guidelines for writing better API Reference documentation, rather than prescriptively mandating absolute, inflexible rules. Some additional experimentation, discussion and real-world proofs of concept will be useful to help inform this.
To that end, I propose opening a PR with the changes previewed above, so others can better render, view and review it for themselves.
My proposed responses to the question follow, for the sake of having something to start with:
When is it good to have an explisit parameters list?
Ideally, it makes sense whenever a non-trivial stdlib function has parameters that are not positional-only, *args/**kwargs, self, etc., follow the standard Python semantics (for example, not cases like the pow function that @EpicWink describes above) and are not otherwise a special case for some reason.
At least for Sphinxdoc, there’s no fixed overhead (just :param NAME: and go), so it makes the guideline simple and consistent to apply, while leaving room for flexibility. Even with only one or a few parameters, a consistent, structured format still not only helps readers find key information faster than reading a paragraph, but also helps writers provide that information, clearly, concisely and explicitly in a manner well-suited to Reference docs.
That said, given it will be applied incrementally over time to existing functions, the initial focus will be on those with relatively many parameters where the net value is the highest. Once we’ve improved those, coupled with other Diataxis-inspired enhancements, we can then focus on functions with fewer parameters.
Likewise, ideally consistently yes, aside from any special cases. At least for Sphinxdoc, since the structure is handled automatically and the types are auto-linked, there is little overhead to writing
:return: A list of matches.
:rtype: list[str]
instead of
It returns a :class:`list` of :class:`str` containing the matches.
whereas the result is more concise, more explicit and easier to navigate and reference. It could be omitted for functions that return None, so long as it is always done consistently, but as all it requires is writing :return: None, is more explicit for readers (particularly beginners, given how often they seem to make the mistake of thinking methods that mutate objects in place return the object) and makes it clear that the return type wasn’t simply implicitly omitted, it still would seem worth doing if we’re revising the function/section anyway.
But likewise, since the improvement will be incremental and alongside adding params and other enhancements, the initial focus will be on functions with many parameters or that are otherwise complex, leaving the simpler cases for later.
If the note is specific to one parameter, ideally with the parameter, for maximum locality and visibility and ease of reference for those reading it. However, due to a Sphinx issue, adding it there causes inconsistent line breaks/spacing, so we should either fix that in Sphinx or with CSS hacks in the theme before we do that, so I didn’t include that in my example for now.
Directly under the class appears to be the standard convention for Sphinxdoc and Numpydoc, and fits with the fact that generally in the stdlib reference, no separate __init__ is shown; the class constructor is already documented directly under the class, so this makes things simpler for both readers and writers and avoids churn. But if an existing module does already document the __init__ and the class itself separately, then that can just be kept for now; while consistency (especially within a module) is nice, I don’t see it worth changing existing content over given that the benefit to readers is much less clear.
I consider type hints (per say), at least in the signature, out of scope here since it will likely be controversial and not everyone is familiar with them. However, the parameter and return types should be included via the standard Sphinxdoc :type: and :rtype: fields, since this is often otherwise left implicit and up to the reader to guess at.
Preferably, the types should be expressed using the standard type annotation syntax if practicable, e.g. float, list[str] or int | None (since it is precise, unambiguous and Sphinx understands it and can automatically link the appropriate types and constructs), but if there isn’t a precise known type, it would be overly complex or impractical to express, or the author simply isn’t familiar with how to do so, it could simply be described in informal language in the field.
I don’t really have a strong or well-informed opinion on this, since CPython is the first project I’ve worked on that duplicates API references in both the docstrings and separate documentation, and I’m honestly not super-familiar with the current practice in this regard. My offhand impression from looking at a number of them a while ago was that the docstrings were somewhat neglected compared with the separate docs, but I’m not sure if that’s still true (if it ever was) and what the current policy and practice is on this, so I’d defer to others on that.
