DOC: improve documentation in new functions

jklymak · jklymak · commit b036e26aad20 · 2021-06-16T12:55:10.000-07:00
diff --git a/lib/matplotlib/_constrained_layout.py b/lib/matplotlib/_constrained_layout.py
@@ -93,8 +93,7 @@ def do_constrained_layout(fig, renderer, h_pad, w_pad,
     """
 
     # make layoutgrid tree...
-    _layoutgrids = None
-    _layoutgrids = _make_layoutgrids(fig, _layoutgrids)
+    _layoutgrids = _make_layoutgrids(fig, None)
     if not _layoutgrids['hasgrids']:
         _api.warn_external('There are no gridspecs with layoutgrids. '
                            'Possibly did not call parent GridSpec with the'
@@ -134,6 +133,14 @@ def do_constrained_layout(fig, renderer, h_pad, w_pad,
 
 
 def _make_layoutgrids(fig, _layoutgrids):
+    """
+    Make the layoutgrid tree.
+
+    (Sub)Figures get a layoutgrid so we can have figure margins.
+
+    Gridspecs that are attached to axes get a layoutgrid so axes
+    can have margins.
+    """
 
     if _layoutgrids is None:
         _layoutgrids = dict()
@@ -144,7 +151,10 @@ def _make_layoutgrids(fig, _layoutgrids):
     else:
         # subfigure
         gs = fig._subplotspec.get_gridspec()
+        # its possible the gridspec containing this subfigure hasn't
+        # been added to the tree yet:
         _layoutgrids = _make_layoutgrids_gs(_layoutgrids, gs)
+        # add the layoutgrid for the subfigure:
         parentlb = _layoutgrids[gs]
         _layoutgrids[fig] = layoutgrid.LayoutGrid(
             parent=parentlb,
@@ -154,9 +164,11 @@ def _make_layoutgrids(fig, _layoutgrids):
             nrows=1, ncols=1,
             parent_pos=(fig._subplotspec.rowspan,
                         fig._subplotspec.colspan))
+    # recursively do all subfigures in this figure...
     for sfig in fig.subfigs:
         _layoutgrids = _make_layoutgrids(sfig, _layoutgrids)
 
+    # for each axes at the local level add its gridspec:
     for ax in fig._localaxes.as_list():
         if hasattr(ax, 'get_subplotspec'):
             gs = ax.get_subplotspec().get_gridspec()
@@ -166,9 +178,14 @@ def _make_layoutgrids(fig, _layoutgrids):
 
 
 def _make_layoutgrids_gs(_layoutgrids, gs):
+    """
+    Make the layoutgrid for a gridspec (and anything nested in the gridspec)
+    """
 
     if gs in _layoutgrids or gs.figure is None:
         return _layoutgrids
+    # in order to do constrained_layout there has to be at least *one*
+    # gridspec in the tree:
     _layoutgrids['hasgrids'] = True
     if not hasattr(gs, '_subplot_spec'):
         # normal gridspec
@@ -182,17 +199,20 @@ def _make_layoutgrids_gs(_layoutgrids, gs):
                 width_ratios=gs.get_width_ratios(),
                 height_ratios=gs.get_height_ratios())
     else:
-        # this is a gridspec inside a subplotspec...
+        # this is a gridspecfromsubplotspec:
         subplot_spec = gs._subplot_spec
         parentgs = subplot_spec.get_gridspec()
+        # if its a nested gridspec its possible the parent is not in there yet:
         if parentgs not in _layoutgrids:
             _layoutgrids = _make_layoutgrids_gs(_layoutgrids, parentgs)
         subspeclb = _layoutgrids[parentgs]
-        _layoutgrids[str(gs)+'top'] = layoutgrid.LayoutGrid(
-            parent=subspeclb,
-            name=subspeclb.name + '.top' + layoutgrid.seq_id(),
-            nrows=1, ncols=1,
-            parent_pos=(subplot_spec.rowspan, subplot_spec.colspan))
+        # gridspecfromsubplotspec need an outer container:
+        if str(gs)+'top' not in _layoutgrids:
+            _layoutgrids[str(gs)+'top'] = layoutgrid.LayoutGrid(
+                parent=subspeclb,
+                name=subspeclb.name + '.top' + layoutgrid.seq_id(),
+                nrows=1, ncols=1,
+                parent_pos=(subplot_spec.rowspan, subplot_spec.colspan))
         _layoutgrids[gs] = layoutgrid.LayoutGrid(
                 parent=_layoutgrids[str(gs)+'top'],
                 name=(_layoutgrids[str(gs)+'top'].name + '.gridspec' +
