Better document multilinebaseline.

anntzer · anntzer · commit 7f3089f5ec3b · 2020-11-26T00:34:00.000+01:00
Also set its default to False instead of None.  (We only check
truthiness, so False and None are equivalent.)

Also don't explicitly set the default verticalalignment in textprops to
"baseline" -- that is already the normal default of `Text`, and is thus
redundant; moreover, the old implementation would cause property
collision if "verticalalignment" (fully spelt out) was passed in
instead (basically, a call to `normalize_kwargs` was missing).

Also minor misc. docstring improvements.
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -779,30 +779,26 @@ class TextArea(OffsetBox):
     @cbook._delete_parameter("3.4", "minimumdescent")
     def __init__(self, s,
                  textprops=None,
-                 multilinebaseline=None,
+                 multilinebaseline=False,
                  minimumdescent=True,
                  ):
         """
         Parameters
         ----------
         s : str
             The text to be displayed.
-
-        textprops : dict, optional
-            Dictionary of keyword parameters to be passed to the
-            `~matplotlib.text.Text` instance contained inside TextArea.
-
-        multilinebaseline : bool, optional
-            If `True`, baseline for multiline text is adjusted so that it is
-            (approximately) center-aligned with singleline text.
-
+        textprops : dict, default: {}
+            Dictionary of keyword parameters to be passed to the `.Text`
+            instance in the TextArea.
+        multilinebaseline : bool, default: False
+            Whether the baseline for multiline text is adjusted so that it
+            is (approximately) center-aligned with single-line text.
         minimumdescent : bool, default: True
             If `True`, the box has a minimum descent of "p".  This is now
             effectively always True.
         """
         if textprops is None:
             textprops = {}
-        textprops.setdefault("va", "baseline")
         self._text = mtext.Text(0, 0, s, **textprops)
         super().__init__()
         self._children = [self._text]
@@ -826,8 +822,10 @@ def set_multilinebaseline(self, t):
         """
         Set multilinebaseline.
 
-        If True, baseline for multiline text is adjusted so that it is
-        (approximately) center-aligned with single-line text.
+        If True, the baseline for multiline text is adjusted so that it is
+        (approximately) center-aligned with single-line text.  This is used
+        e.g. by the legend implementation so that single-line labels are
+        baseline-aligned, but multiline labels are "center"-aligned with them.
         """
         self._multilinebaseline = t
         self.stale = True
