<p dir="auto">I would like to propose the following amendments to the docstring style guide.</p>
<ul dir="auto">
<li>
<p dir="auto">Drop the "optional" note next to optional parameters:</p>
<ul dir="auto">
<li>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.</li>
<li>"Optional" is not sufficient to indicate whether a parameter is keyword-only or not (currently rare, but possibly less so in the future).</li>
<li>Due to Matplotlib's API design, the vast majority of parameters are optional anyways.</li>
</ul>
</li>
<li>
<p dir="auto">Stop mentioning the default value for optional arguments, unless it has a non-obvious meaning (typically when <code class="notranslate">None</code> means <code class="notranslate">rcParams["foo"]</code>).<br>
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...).<br>
Note that numpydoc says "Optional keyword parameters have default values, which are displayed as part of the function signature. They <em>can</em> also be <em>detailed</em> in the description." (emphasis mine).  The example they give is in fact one where the default has a non-obvious meaning.</p>
</li>
</ul>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="Description of parameter `x` (the default is -1, which implies summation
over all axes)."><pre class="notranslate"><code class="notranslate">Description of parameter `x` (the default is -1, which implies summation
over all axes).
</code></pre></div>
<ul dir="auto">
<li>Progressively switch to using type hints syntax for "composite" types (<code class="notranslate">List[int]</code>, 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 towards <code class="notranslate">auto</code> everywhere), but it does provide a standard syntax that is reasonable.  The only exception is that I would keep <code class="notranslate">type1 or type2</code> (which is understood by Sphinx) rather than <code class="notranslate">Union[type1, type2]</code>.  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.</li>
</ul>
<p dir="auto">This is on current master I can't reproduce this using 1.4.3. I guess it relates to the stale auto redraw handling?</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="from mpl_toolkits.mplot3d import Axes3D


fig = plt.figure(figsize=(6.5,5.5))
ax = fig.add_subplot(1, 1, 1, projection='3d')
xs = np.random.rand(10)
ys = np.random.rand(10)
zs = np.random.rand(10)
ax.set_aspect('equal')

ax.scatter(xs, ys, zs)
ax.set_xlim(0,1)
ax.set_ylim(0,1)
ax.set_zlim(0,1)
fig.tight_layout()"><pre class="notranslate"><code class="notranslate">from mpl_toolkits.mplot3d import Axes3D


fig = plt.figure(figsize=(6.5,5.5))
ax = fig.add_subplot(1, 1, 1, projection='3d')
xs = np.random.rand(10)
ys = np.random.rand(10)
zs = np.random.rand(10)
ax.set_aspect('equal')

ax.scatter(xs, ys, zs)
ax.set_xlim(0,1)
ax.set_ylim(0,1)
ax.set_zlim(0,1)
fig.tight_layout()
</code></pre></div>
<p dir="auto">results in</p>
<p dir="auto"><a target="_blank" rel="noopener noreferrer nofollow" href="https://cloud.githubusercontent.com/assets/548266/9378877/db5c894e-471c-11e5-89e4-b7d1611c3f53.png"><img src="https://cloud.githubusercontent.com/assets/548266/9378877/db5c894e-471c-11e5-89e4-b7d1611c3f53.png" alt="download 2" style="max-width: 100%;"></a></p>
<p dir="auto">Rotating the figure restores the correct axes.  I can't reproduce it with QT5Agg or GTK3Agg</p>
<p dir="auto">It seems like both the equal axis z and the original z axis are drawn on top of each other. It doesn't seem to happen in regular 2D plots.</p>