From 9aeb97cceab369fb02b7e4c2cf5933e05d8eebc3 Mon Sep 17 00:00:00 2001
From: Harley Acheson <harley.acheson@gmail.com>
Date: Tue, 18 Feb 2025 05:26:12 +0100
Subject: [PATCH] Cleanup: Improved Comments in ui_def_but_rna__menu

Nothing but improvements to comments in this area of code to better
explain the complexity of Emum list row and column calculation. These
things change wrapping and column count to suit available space and
needs better explanation.

Pull Request: https://projects.blender.org/blender/blender/pulls/134719
---
 source/blender/editors/interface/interface.cc | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/source/blender/editors/interface/interface.cc b/source/blender/editors/interface/interface.cc
index 10dd25aed15..bf4f4666643 100644
--- a/source/blender/editors/interface/interface.cc
+++ b/source/blender/editors/interface/interface.cc
@@ -4482,12 +4482,13 @@ static void ui_def_but_rna__menu(bContext *C, uiLayout *layout, void *but_p)
   int rows = 0;
 
   const wmWindow *win = CTX_wm_window(C);
+
+  /* Calculate the maximum number of rows that can fit in half the height of this window. */
   const float row_height = float(UI_UNIT_Y) / but->block->aspect;
-  /* Calculate max_rows from how many rows can fit in this window. */
   const float vertical_space = (float(WM_window_native_pixel_y(win)) / 2.0f) - (UI_UNIT_Y * 3.0f);
   const int max_rows = int(vertical_space / row_height) - 1;
-  float text_width = 0.0f;
 
+  float text_width = 0.0f;
   BLF_size(BLF_default(), UI_style_get()->widget.points * UI_SCALE_FAC);
   int col_rows = 0;
   float col_width = 0.0f;
@@ -4517,12 +4518,16 @@ static void ui_def_but_rna__menu(bContext *C, uiLayout *layout, void *but_p)
   text_width += col_width;
   text_width /= but->block->aspect;
 
-  /* Wrap long single-column lists. */
   if (categories == 0) {
+    /* Long lists without categories (section titles) can be wrapped
+     * to any nice combination of columns and rows. First use (long-
+     * standing) code that wraps most lists pleasantly. */
     columns = std::max((totitems + 20) / 20, 1);
     if (columns > 8) {
       columns = (totitems + 25) / 25;
     }
+    /* If above results in more rows than can fit in available vertical
+     * space, then break it into columns of rows of maximum length. */
     if ((totitems / columns) > max_rows) {
       columns = std::max((totitems + col_rows) / max_rows, 1);
     }
@@ -4532,7 +4537,8 @@ static void ui_def_but_rna__menu(bContext *C, uiLayout *layout, void *but_p)
     }
   }
 
-  /* If the estimated width is greater than available size, collapse to one column. */
+  /* If the estimated width of the menu is wider than the width of
+   * this window, then we have to collapse it to a single column. */
   if (columns > 1 && text_width > WM_window_native_pixel_x(win)) {
     columns = 1;
     rows = totitems;