I don't think we have any yet, but we are going to eventually have required keyword arguments. Do we want to call those out as explicitly required?

I am 50/50 on this change. See the argument for reducing clutter, but it means you now have to look in two places instead of one to get all of the information you need.

I‘d point out mandatory kwargs explicitly rather than optional ones.

There will be far less mandatory ones, and the „standard“ notion of Python kwargs is optional.

Another weak argument for removing optional is that type definitions in numpydoc have to be on a logical line. You run into conflicts more often between the 80 char limit and backslash continuation, which must be continued with 0-indent on the he following line.

I'm +1 on this change, especially for cases where the default is spelled out on the same line anyways (in which case it's clear it's optional...).

For reference:

• NumPy and SciPy both use name : type, optional. Defaults are only written in the body of the docstring.
• Pandas uses name : type, default xxx.

Should we be a little more defensive and specific?

For keyword arguments use {name} : {type}, default: {val}, or if the default is not simple to describe use {name} : {type}, optional and describe the default in the text.

looks like a good start

Reworded according to #14862 (comment)

@tacaswell does the revised version reduce your concern?