Merge pull request matplotlib#22420 from anntzer/figdoc

Update plt.figure() docstring.

Author: timhoffm

lib/matplotlib/pyplot.py

@@ -712,40 +712,32 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
         If False, suppress drawing the figure frame.
 
     FigureClass : subclass of `~matplotlib.figure.Figure`
-        Optionally use a custom `.Figure` instance.
+        If set, an instance of this subclass will be created, rather than a
+        plain `.Figure`.
 
     clear : bool, default: False
         If True and the figure already exists, then it is cleared.
 
-    tight_layout : bool or dict, default: :rc:`figure.autolayout`
-        If ``False`` use *subplotpars*. If ``True`` adjust subplot
-        parameters using `.tight_layout` with default padding.
-        When providing a dict containing the keys ``pad``, ``w_pad``,
-        ``h_pad``, and ``rect``, the default `.tight_layout` paddings
-        will be overridden.
+    layout : {'constrained', 'tight', `.LayoutEngine`, None}, default: None
+        The layout mechanism for positioning of plot elements to avoid
+        overlapping Axes decorations (labels, ticks, etc). Note that layout
+        managers can measurably slow down figure display. Defaults to *None*
+        (but see the documentation of the `.Figure` constructor regarding the
+        interaction with rcParams).
 
-    constrained_layout : bool, default: :rc:`figure.constrained_layout.use`
-        If ``True`` use constrained layout to adjust positioning of plot
-        elements.  Like ``tight_layout``, but designed to be more
-        flexible.  See
-        :doc:`/tutorials/intermediate/constrainedlayout_guide`
-        for examples.  (Note: does not work with `add_subplot` or
-        `~.pyplot.subplot2grid`.)
-
-
-    **kwargs : optional
-        See `~.matplotlib.figure.Figure` for other possible arguments.
+    **kwargs
+        Additional keyword arguments are passed to the `.Figure` constructor.
 
     Returns
     -------
     `~matplotlib.figure.Figure`
-        The `.Figure` instance returned will also be passed to
-        new_figure_manager in the backends, which allows to hook custom
-        `.Figure` classes into the pyplot interface. Additional kwargs will be
-        passed to the `.Figure` init function.
 
     Notes
     -----
+    Newly created figures will be passed to the
+    `~.backend_template.new_figure_manager` function provided by the current
+    backend, which will install a canvas and a manager on the figure.
+
     If you are creating many figures, make sure you explicitly call
     `.pyplot.close` on the figures you are not using, because this will
     enable pyplot to properly clean up the memory.