DOC: Improve docs of legend loc=best (#30854)

timhoffm · rcomer · web-flow · commit b70e3246b10d · 2025-12-16T12:11:13.000Z
* DOC: Improve docs of legend loc=best Closes #29319. * Update lib/matplotlib/legend.py Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com> --------- Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -303,8 +303,13 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 _loc_doc_best = """
     The string ``'best'`` places the legend at the location, among the nine
     locations defined so far, with the minimum overlap with other drawn
-    artists.  This option can be quite slow for plots with large amounts of
-    data; your plotting speed may benefit from providing a specific location.
+    artists.  This currently takes into account most, but not all, artists
+    added to the Axes via plotting functions. In particular it does not consider
+    inset axes, titles, or axis labels.
+
+    The computation of the best position can be expensive for plots with large
+    amounts of data. If speed becomes a concern, you may may benefit from
+    providing a specific location.
 """
 
 _legend_kw_axes_st = (
