From bc8293a9e5b727b54e7169c1e924efce6efcb1b1 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sat, 30 Jan 2016 21:39:09 +0100
Subject: [PATCH] Update wxMenu::UpdateUI() parameter comment and documentation

The argument to this method should basically just never be used, so while we
still keep it for compatibility (because it doesn't cost anything to do it),
make it clear that it should never be specified in the new code and, also,
that this function is actually only used inside wxWidgets and shouldn't be
normally called from outside of the library at all.
---
 include/wx/menu.h      |  8 +++++---
 interface/wx/menu.h    | 10 ++++++----
 src/common/menucmn.cpp |  5 +----
 3 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/include/wx/menu.h b/include/wx/menu.h
index 252ea54ea7..b733467604 100644
--- a/include/wx/menu.h
+++ b/include/wx/menu.h
@@ -275,9 +275,11 @@ public:
     // implementation helpers
     // ----------------------
 
-    // Updates the UI for a menu and all submenus recursively. source is the
-    // object that has the update event handlers defined for it. If NULL, the
-    // menu or associated window will be used.
+    // Updates the UI for a menu and all submenus recursively by generating
+    // wxEVT_UPDATE_UI for all the items.
+    //
+    // Do not use the "source" argument, it allows to override the event
+    // handler to use for these events, but this should never be needed.
     void UpdateUI(wxEvtHandler* source = NULL);
 
     // get the menu bar this menu is attached to (may be NULL, always NULL for
diff --git a/interface/wx/menu.h b/interface/wx/menu.h
index 989fc982e0..3157e3a75b 100644
--- a/interface/wx/menu.h
+++ b/interface/wx/menu.h
@@ -1036,11 +1036,13 @@ public:
     virtual void SetTitle(const wxString& title);
 
     /**
-        Sends events to @a source (or owning window if @NULL) to update the
-        menu UI.
+        Update the state of all menu items, recursively, by generating @c
+        wxEVT_UPDATE_UI events for them.
 
-        This is called just before the menu is popped up with wxWindow::PopupMenu,
-        but the application may call it at other times if required.
+        This is an internal wxWidgets function and shouldn't normally be called
+        from outside of the library. If it is called, @a source argument should
+        not be used, it is deprecated and exists only for backwards
+        compatibility.
     */
     void UpdateUI(wxEvtHandler* source = NULL);
 
diff --git a/src/common/menucmn.cpp b/src/common/menucmn.cpp
index a70ef29618..2808af69d6 100644
--- a/src/common/menucmn.cpp
+++ b/src/common/menucmn.cpp
@@ -593,9 +593,6 @@ wxMenuItem* wxMenuBase::FindItemByPosition(size_t position) const
 // wxMenu helpers used by derived classes
 // ----------------------------------------------------------------------------
 
-// Update a menu and all submenus recursively. source is the object that has
-// the update event handlers defined for it. If NULL, the menu or associated
-// window will be used.
 void wxMenuBase::UpdateUI(wxEvtHandler* source)
 {
     wxWindow * const win = GetWindow();
@@ -1095,7 +1092,7 @@ void wxMenuBarBase::UpdateMenus()
     {
         menu = GetMenu( n );
         if (menu != NULL)
-            menu->UpdateUI( NULL );
+            menu->UpdateUI();
     }
 }