Make optional in docstrings optional

timhoffm · timhoffm · commit a039e205ab9d · 2019-07-23T01:26:29.000+02:00
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -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
         --------
@@ -420,9 +420,17 @@ 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*. This removes unnecessary clutter. The optional aspect is already
+clear from the presence of a default parameter (visible in the signature or
+expicit in the docstring). *optional* may be scarcely used when this
+information is not available in the context of the docstring (e.g. when
+it's hidden behind ``*args`` or ``*kwargs``).
+
 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``,
@@ -460,7 +468,7 @@ Use abbreviated links ```.Normalize``` in the text.
 
 .. code-block:: rst
 
-  norm : `~matplotlib.colors.Normalize`, optional
+  norm : `~matplotlib.colors.Normalize`
      A `.Normalize` instance is used to scale luminance data to 0, 1.
 
 ``See also`` sections
@@ -489,7 +497,7 @@ result in a lot of whitespace within the line):
       Parameters
       ----------
       projection : {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
-  'rectilinear'}, optional
+  'rectilinear'}
           The projection type of the axes.
 
       ...
