Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Make optional in docstrings optional #14862

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 12, 2019
Merged

Make optional in docstrings optional #14862

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -350,19 +350,19 @@ An example docstring looks like:
Respective beginning and end of each line. If scalars are
provided, all lines will have the same length.

colors : array-like of colors, optional, default: 'k'
colors : array-like of colors, default: 'k'

linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional
linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, default: 'solid'

label : string, optional, default: ''
label : str, default: ''

Returns
-------
lines : `~matplotlib.collections.LineCollection`

Other Parameters
----------------
**kwargs : `~matplotlib.collections.LineCollection` properties.
**kwargs : `~matplotlib.collections.LineCollection` properties

See also
--------
Expand Down Expand Up @@ -420,9 +420,19 @@ precisely in the text.
Generally, the `numpydoc docstring guide`_ conventions apply. The following
rules expand on them where the numpydoc conventions are not specific.

As opposed to the numpydoc guide, parameters need not be marked as
*optional* if they have a simple default. This removes unnecessary clutter.
The optional aspect is already clear from the presence of a default value.
More specifically

- use `{name} : {type}, default: {val}` when possible.
- use `{name} : {type}, optional` and describe the default in the text if
in cannot be explained sufficiently in the above way.

Use ``float`` for a type that can be any number.

Use ``(float, float)`` to describe a 2D position.
Use ``(float, float)`` to describe a 2D position. The parentheses should be
included to make the tuple-ness more obvious.

Use ``array-like`` for homogeneous numeric sequences, which could
typically be a numpy.array. Dimensionality may be specified using ``2D``,
Expand Down