The sentence "If any kwarg is None, default to the current value, if
set, otherwise to rc." is clearly wrong given the lines just below,
which overwrite the current value unconditonally:

for k, v in kwargs.items():
    if k in self._AllowedKeys:
        setattr(self, k, v)

This can also be checked with e.g.

from matplotlib.gridspec import GridSpec
from matplotlib import pyplot as plt
gs = GridSpec(1, 1, left=.5)
gs.update(left=None)
plt.figure().add_subplot(gs[0, 0])
plt.show()

where the update reset left to the rc value.

Given that the behavior has been like that ever since gridspec was added
to matplotlib, it seems better to update the docstring.

@jklymak In the same module there's also

    def get_subplot_params(self, figure=None, fig=None):
        """
        Return a dictionary of subplot layout parameters. The default
        parameters are from rcParams unless a figure attribute is set.
        """

but here too the implementation clearly always drops the figure attributes; IOW it always returns a copy of self completely ignoring figure. Given that you last touched this with the constrainedlayout work I don't know what the best approach is, but perhaps we can just get rid of that method...

PR Summary

PR Checklist

• Has Pytest style unit tests
• Code is Flake 8 compliant
• New features are documented, with examples if plot related
• Documentation is sphinx and numpydoc compliant
• Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
• Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way