Description
I would like to propose the following amendments to the docstring style guide.
-
Drop the "optional" note next to optional parameters:
- Most tools that I can think of for viewing a function docstring will also display the function signature, which displays whether a parameter is optional in a much more prominent manner.
- "Optional" is not sufficient to indicate whether a parameter is keyword-only or not (currently rare, but possibly less so in the future).
- Due to Matplotlib's API design, the vast majority of parameters are optional anyways.
-
Stop mentioning the default value for optional arguments, unless it has a non-obvious meaning (typically when
NonemeansrcParams["foo"]).
Likewise this is mostly duplicating information available in the signature; moreover, right now the default value is given at the end of the doc for each parameter which is not even a really obvious place to find it (it would have been better if it went right next to the parameter name, but what can you do...).
Note that numpydoc says "Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the description." (emphasis mine). The example they give is in fact one where the default has a non-obvious meaning.
Description of parameter `x` (the default is -1, which implies summation
over all axes).
- Progressively switch to using type hints syntax for "composite" types (
List[int], etc.). I'm actually not a huge fan of the direction that the Python dev team is taking on explicit type hints everywhere in general (I think it's a step in the wrong direction - compare with C++ which is moving towardsautoeverywhere), but it does provide a standard syntax that is reasonable. The only exception is that I would keeptype1 or type2(which is understood by Sphinx) rather thanUnion[type1, type2]. We also need to decide whether to have a standard syntax for array-likes, although that's probably more of an upstream (i.e. numpydoc-level) issue and can be done in a later stage.