Cleanup: callback naming for search button & update doc-strings

Callback naming didn't always make it clear which function updated
the search contents and the function used to execute the action.

8 files changed, 74 insertions, 58 deletions

diff --git a/source/blender/editors/include/UI_interface.h b/source/blender/editors/include/UI_interface.h
index 2ea03fa5bc2..4aca3b41381 100644
--- a/source/blender/editors/include/UI_interface.h
+++ b/source/blender/editors/include/UI_interface.h
@@ -1581,7 +1581,7 @@ void UI_but_func_search_set(uiBut *but,
                             uiButSearchUpdateFn search_update_fn,
                             void *arg,
                             uiButSearchArgFreeFn search_arg_free_fn,
-                            uiButHandleFunc handle_fn,
+                            uiButHandleFunc search_exec_fn,
                             void *active);
 void UI_but_func_search_set_context_menu(uiBut *but, uiButSearchContextMenuFn context_menu_fn);
 void UI_but_func_search_set_sep_string(uiBut *but, const char *search_sep_string);
diff --git a/source/blender/editors/interface/interface.c b/source/blender/editors/interface/interface.c
index 93caa97db73..18df67be545 100644
--- a/source/blender/editors/interface/interface.c
+++ b/source/blender/editors/interface/interface.c
@@ -6351,18 +6351,24 @@ uiBut *uiDefSearchBut(uiBlock *block,
 }
 
 /**
- * \param search_func, bfunc: both get it as \a arg.
- * \param arg: user value,
- * \param active: when set, button opens with this item visible and selected.
- * \param separator_string: when not NULL, this string is used as a separator,
- * showing the icon and highlighted text after the last instance of this string.
+ * \note The item-pointer (referred to below) is a per search item user pointer
+ * passed to #UI_search_item_add (stored in  #uiSearchItems.pointers).
+ *
+ * \param search_create_fn: Function to create the menu.
+ * \param search_update_fn: Function to refresh search content after the search text has changed.
+ * \param arg: user value.
+ * \param search_arg_free_fn: When non-null, use this function to free \a arg.
+ * \param search_exec_fn: Function that executes the action, gets \a arg as the first argument.
+ * The second argument as the active item-pointer
+ * \param active: When non-null, this item-pointer item will be visible and selected,
+ * otherwise the first item will be selected.
  */
 void UI_but_func_search_set(uiBut *but,
                             uiButSearchCreateFn search_create_fn,
                             uiButSearchUpdateFn search_update_fn,
                             void *arg,
                             uiButSearchArgFreeFn search_arg_free_fn,
-                            uiButHandleFunc handle_fn,
+                            uiButHandleFunc search_exec_fn,
                             void *active)
 {
   /* needed since callers don't have access to internal functions
@@ -6389,7 +6395,7 @@ void UI_but_func_search_set(uiBut *but,
   search->arg = arg;
   search->arg_free_fn = search_arg_free_fn;
 
-  if (handle_fn) {
+  if (search_exec_fn) {
 #ifdef DEBUG
     if (but->func) {
       /* watch this, can be cause of much confusion, see: T47691 */
@@ -6397,7 +6403,7 @@ void UI_but_func_search_set(uiBut *but,
              __func__);
     }
 #endif
-    UI_but_func_set(but, handle_fn, search->arg, active);
+    UI_but_func_set(but, search_exec_fn, search->arg, active);
   }
 
   /* search buttons show red-alert if item doesn't exist, not for menus */
@@ -6415,6 +6421,10 @@ void UI_but_func_search_set_context_menu(uiBut *but, uiButSearchContextMenuFn co
   search->context_menu_fn = context_menu_fn;
 }
 
+/**
+ * \param separator_string: when not NULL, this string is used as a separator,
+ * showing the icon and highlighted text after the last instance of this string.
+ */
 void UI_but_func_search_set_sep_string(uiBut *but, const char *search_sep_string)
 {
   struct uiButSearchData *search = but->search;
@@ -6422,10 +6432,10 @@ void UI_but_func_search_set_sep_string(uiBut *but, const char *search_sep_string
 }
 
 /* Callbacks for operator search button. */
-static void operator_enum_search_cb(const struct bContext *C,
-                                    void *but,
-                                    const char *str,
-                                    uiSearchItems *items)
+static void operator_enum_search_update_fn(const struct bContext *C,
+                                           void *but,
+                                           const char *str,
+                                           uiSearchItems *items)
 {
   wmOperatorType *ot = ((uiBut *)but)->optype;
   PropertyRNA *prop = ot->prop;
@@ -6462,7 +6472,7 @@ static void operator_enum_search_cb(const struct bContext *C,
   }
 }
 
-static void operator_enum_call_cb(struct bContext *UNUSED(C), void *but, void *arg2)
+static void operator_enum_search_exec_fn(struct bContext *UNUSED(C), void *but, void *arg2)
 {
   wmOperatorType *ot = ((uiBut *)but)->optype;
   PointerRNA *opptr = UI_but_operator_ptr_get(but); /* Will create it if needed! */
@@ -6505,10 +6515,10 @@ uiBut *uiDefSearchButO_ptr(uiBlock *block,
   but = uiDefSearchBut(block, arg, retval, icon, maxlen, x, y, width, height, a1, a2, tip);
   UI_but_func_search_set(but,
                          ui_searchbox_create_generic,
-                         operator_enum_search_cb,
+                         operator_enum_search_update_fn,
                          but,
                          NULL,
-                         operator_enum_call_cb,
+                         operator_enum_search_exec_fn,
                          NULL);
 
   but->optype = ot;
diff --git a/source/blender/editors/interface/interface_layout.c b/source/blender/editors/interface/interface_layout.c
index 2ed6a87840b..9c59901083c 100644
--- a/source/blender/editors/interface/interface_layout.c
+++ b/source/blender/editors/interface/interface_layout.c
@@ -2645,7 +2645,7 @@ static void search_id_collection(StructRNA *ptype, PointerRNA *r_ptr, PropertyRN
   RNA_STRUCT_END;
 }
 
-static void ui_rna_collection_search_free_cb(void *ptr)
+static void ui_rna_collection_search_arg_free_fn(void *ptr)
 {
   uiRNACollectionSearch *coll_search = ptr;
   UI_butstore_free(coll_search->butstore_block, coll_search->butstore);
@@ -2699,7 +2699,7 @@ void ui_but_add_search(
                            ui_searchbox_create_generic,
                            ui_rna_collection_search_update_fn,
                            coll_search,
-                           ui_rna_collection_search_free_cb,
+                           ui_rna_collection_search_arg_free_fn,
                            NULL,
                            NULL);
   }
diff --git a/source/blender/editors/interface/interface_template_search_menu.c b/source/blender/editors/interface/interface_template_search_menu.c
index 8bd61ccd038..9d7f813d204 100644
--- a/source/blender/editors/interface/interface_template_search_menu.c
+++ b/source/blender/editors/interface/interface_template_search_menu.c
@@ -832,7 +832,7 @@ static struct MenuSearch_Data *menu_items_from_ui_create(
   return data;
 }
 
-static void menu_items_from_ui_destroy(void *data_v)
+static void menu_search_arg_free_fn(void *data_v)
 {
   struct MenuSearch_Data *data = data_v;
   LISTBASE_FOREACH (struct MenuSearch_Item *, item, &data->items) {
@@ -854,7 +854,7 @@ static void menu_items_from_ui_destroy(void *data_v)
   MEM_freeN(data);
 }
 
-static void menu_call_fn(bContext *C, void *UNUSED(arg1), void *arg2)
+static void menu_search_exec_fn(bContext *C, void *UNUSED(arg1), void *arg2)
 {
   struct MenuSearch_Item *item = arg2;
   if (item == NULL) {
@@ -916,10 +916,10 @@ static void menu_call_fn(bContext *C, void *UNUSED(arg1), void *arg2)
   }
 }
 
-static void menu_search_cb(const bContext *UNUSED(C),
-                           void *arg,
-                           const char *str,
-                           uiSearchItems *items)
+static void menu_search_update_fn(const bContext *UNUSED(C),
+                                  void *arg,
+                                  const char *str,
+                                  uiSearchItems *items)
 {
   struct MenuSearch_Data *data = arg;
   const size_t str_len = strlen(str);
@@ -956,10 +956,10 @@ static void menu_search_cb(const bContext *UNUSED(C),
  * a separate context menu just for the search, however this is fairly involved.
  * \{ */
 
-static bool menu_search_context_menu_fn(struct bContext *C,
-                                        void *arg,
-                                        void *active,
-                                        const struct wmEvent *UNUSED(event))
+static bool ui_search_menu_create_context_menu(struct bContext *C,
+                                               void *arg,
+                                               void *active,
+                                               const struct wmEvent *UNUSED(event))
 {
   struct MenuSearch_Data *data = arg;
   struct MenuSearch_Item *item = active;
@@ -1010,14 +1010,15 @@ void UI_but_func_menu_search(uiBut *but)
   struct MenuSearch_Data *data = menu_items_from_ui_create(
       C, win, area, region, include_all_areas);
   UI_but_func_search_set(but,
+                         /* Generic callback. */
                          ui_searchbox_create_menu,
-                         menu_search_cb,
+                         menu_search_update_fn,
                          data,
-                         menu_items_from_ui_destroy,
-                         menu_call_fn,
+                         menu_search_arg_free_fn,
+                         menu_search_exec_fn,
                          NULL);
 
-  UI_but_func_search_set_context_menu(but, menu_search_context_menu_fn);
+  UI_but_func_search_set_context_menu(but, ui_search_menu_create_context_menu);
   UI_but_func_search_set_sep_string(but, MENU_SEP);
 }
 
diff --git a/source/blender/editors/interface/interface_template_search_operator.c b/source/blender/editors/interface/interface_template_search_operator.c
index 975ee5fe43d..cdf87103587 100644
--- a/source/blender/editors/interface/interface_template_search_operator.c
+++ b/source/blender/editors/interface/interface_template_search_operator.c
@@ -50,7 +50,7 @@
 /** \name Operator Search Template Implementation
  * \{ */
 
-static void operator_call_cb(bContext *C, void *UNUSED(arg1), void *arg2)
+static void operator_search_exec_fn(bContext *C, void *UNUSED(arg1), void *arg2)
 {
   wmOperatorType *ot = arg2;
 
@@ -59,10 +59,10 @@ static void operator_call_cb(bContext *C, void *UNUSED(arg1), void *arg2)
   }
 }
 
-static void operator_search_cb(const bContext *C,
-                               void *UNUSED(arg),
-                               const char *str,
-                               uiSearchItems *items)
+static void operator_search_update_fn(const bContext *C,
+                                      void *UNUSED(arg),
+                                      const char *str,
+                                      uiSearchItems *items)
 {
   GHashIterator iter;
   const size_t str_len = strlen(str);
@@ -125,8 +125,13 @@ static void operator_search_cb(const bContext *C,
 
 void UI_but_func_operator_search(uiBut *but)
 {
-  UI_but_func_search_set(
-      but, ui_searchbox_create_operator, operator_search_cb, NULL, false, operator_call_cb, NULL);
+  UI_but_func_search_set(but,
+                         ui_searchbox_create_operator,
+                         operator_search_update_fn,
+                         NULL,
+                         false,
+                         operator_search_exec_fn,
+                         NULL);
 }
 
 void uiTemplateOperatorSearch(uiLayout *layout)
diff --git a/source/blender/editors/interface/interface_templates.c b/source/blender/editors/interface/interface_templates.c
index 08e077f4cfe..75945cadbb9 100644
--- a/source/blender/editors/interface/interface_templates.c
+++ b/source/blender/editors/interface/interface_templates.c
@@ -205,7 +205,7 @@ static uiBlock *template_common_search_menu(const bContext *C,
                                             ARegion *region,
                                             uiButSearchUpdateFn search_update_fn,
                                             void *search_arg,
-                                            uiButHandleFunc handle_func,
+                                            uiButHandleFunc search_exec_fn,
                                             void *active_item,
                                             const int preview_rows,
                                             const int preview_cols,
@@ -282,7 +282,7 @@ static uiBlock *template_common_search_menu(const bContext *C,
                          search_update_fn,
                          search_arg,
                          NULL,
-                         handle_func,
+                         search_exec_fn,
                          active_item);
 
   UI_block_bounds_set_normal(block, 0.3f * U.widget_unit);
@@ -315,7 +315,7 @@ typedef struct TemplateID {
 } TemplateID;
 
 /* Search browse menu, assign  */
-static void template_ID_set_property_cb(bContext *C, void *arg_template, void *item)
+static void template_ID_set_property_exec_fn(bContext *C, void *arg_template, void *item)
 {
   TemplateID *template_ui = (TemplateID *)arg_template;
 
@@ -470,7 +470,7 @@ static uiBlock *id_search_menu(bContext *C, ARegion *region, void *arg_litem)
                                      region,
                                      id_search_update_fn,
                                      &template_ui,
-                                     template_ID_set_property_cb,
+                                     template_ID_set_property_exec_fn,
                                      active_item_ptr.data,
                                      template_ui.prv_rows,
                                      template_ui.prv_cols,
@@ -1182,7 +1182,7 @@ static void template_ID_tabs(bContext *C,
                                                0.0f,
                                                0.0f,
                                                "");
-    UI_but_funcN_set(&tab->but, template_ID_set_property_cb, MEM_dupallocN(template), id);
+    UI_but_funcN_set(&tab->but, template_ID_set_property_exec_fn, MEM_dupallocN(template), id);
     tab->but.custom_data = (void *)id;
     tab->but.dragpoin = id;
     tab->menu = mt;
@@ -1528,7 +1528,7 @@ typedef struct TemplateSearch {
   int preview_rows, preview_cols;
 } TemplateSearch;
 
-static void template_search_handle_cb(bContext *C, void *arg_template, void *item)
+static void template_search_exec_fn(bContext *C, void *arg_template, void *item)
 {
   TemplateSearch *template_search = arg_template;
   uiRNACollectionSearch *coll_search = &template_search->search_data;
@@ -1554,7 +1554,7 @@ static uiBlock *template_search_menu(bContext *C, ARegion *region, void *arg_tem
                                      region,
                                      ui_rna_collection_search_update_fn,
                                      &template_search,
-                                     template_search_handle_cb,
+                                     template_search_exec_fn,
                                      active_ptr.data,
                                      template_search.preview_rows,
                                      template_search.preview_cols,
diff --git a/source/blender/editors/space_node/node_select.c b/source/blender/editors/space_node/node_select.c
index 53938ff4d41..793747ee266 100644
--- a/source/blender/editors/space_node/node_select.c
+++ b/source/blender/editors/space_node/node_select.c
@@ -1116,10 +1116,10 @@ void NODE_OT_select_same_type_step(wmOperatorType *ot)
  * \{ */
 
 /* generic  search invoke */
-static void node_find_cb(const struct bContext *C,
-                         void *UNUSED(arg),
-                         const char *str,
-                         uiSearchItems *items)
+static void node_find_update_fn(const struct bContext *C,
+                                void *UNUSED(arg),
+                                const char *str,
+                                uiSearchItems *items)
 {
   SpaceNode *snode = CTX_wm_space_node(C);
   bNode *node;
@@ -1142,7 +1142,7 @@ static void node_find_cb(const struct bContext *C,
   }
 }
 
-static void node_find_call_cb(struct bContext *C, void *UNUSED(arg1), void *arg2)
+static void node_find_exec_fn(struct bContext *C, void *UNUSED(arg1), void *arg2)
 {
   SpaceNode *snode = CTX_wm_space_node(C);
   bNode *active = arg2;
@@ -1182,7 +1182,7 @@ static uiBlock *node_find_menu(bContext *C, ARegion *region, void *arg_op)
                        0,
                        0,
                        "");
-  UI_but_func_search_set(but, NULL, node_find_cb, op->type, NULL, node_find_call_cb, NULL);
+  UI_but_func_search_set(but, NULL, node_find_update_fn, op->type, NULL, node_find_exec_fn, NULL);
   UI_but_flag_enable(but, UI_BUT_ACTIVATE_ON_INIT);
 
   /* fake button, it holds space for search items */
diff --git a/source/blender/editors/space_outliner/outliner_tools.c b/source/blender/editors/space_outliner/outliner_tools.c
index e4449d21405..0ccf982fd29 100644
--- a/source/blender/editors/space_outliner/outliner_tools.c
+++ b/source/blender/editors/space_outliner/outliner_tools.c
@@ -553,10 +553,10 @@ static void merged_element_search_cb_recursive(
 }
 
 /* Get a list of elements that match the search string */
-static void merged_element_search_cb(const bContext *UNUSED(C),
-                                     void *data,
-                                     const char *str,
-                                     uiSearchItems *items)
+static void merged_element_search_update_fn(const bContext *UNUSED(C),
+                                            void *data,
+                                            const char *str,
+                                            uiSearchItems *items)
 {
   MergedSearchData *search_data = (MergedSearchData *)data;
   TreeElement *parent = search_data->parent_element;
@@ -568,7 +568,7 @@ static void merged_element_search_cb(const bContext *UNUSED(C),
 }
 
 /* Activate an element from the merged element search menu */
-static void merged_element_search_call_cb(struct bContext *C, void *UNUSED(arg1), void *element)
+static void merged_element_search_exec_fn(struct bContext *C, void *UNUSED(arg1), void *element)
 {
   SpaceOutliner *soops = CTX_wm_space_outliner(C);
   TreeElement *te = (TreeElement *)element;
@@ -600,7 +600,7 @@ static uiBlock *merged_element_search_menu(bContext *C, ARegion *region, void *d
   but = uiDefSearchBut(
       block, search, 0, ICON_VIEWZOOM, sizeof(search), 10, 10, menu_width, UI_UNIT_Y, 0, 0, "");
   UI_but_func_search_set(
-      but, NULL, merged_element_search_cb, data, NULL, merged_element_search_call_cb, NULL);
+      but, NULL, merged_element_search_update_fn, data, NULL, merged_element_search_exec_fn, NULL);
   UI_but_flag_enable(but, UI_BUT_ACTIVATE_ON_INIT);
 
   /* Fake button to hold space for search items */