From 4186292e11ac1c608a66ef1d9838f5493a5f6ef5 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sat, 24 Jul 2021 17:20:00 +0100
Subject: [PATCH] Improve wxIMPLEMENT_APP() documentation

Explain that this macro defines the application entry point.

Also document wxIMPLEMENT_WXWIN_MAIN which wasn't documented at all
previously.
---
 docs/doxygen/overviews/app.h |  9 +++------
 interface/wx/app.h           | 31 +++++++++++++++++++++++++++++--
 2 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/docs/doxygen/overviews/app.h b/docs/doxygen/overviews/app.h
index 6d8da730d1..cb2ae2e963 100644
--- a/docs/doxygen/overviews/app.h
+++ b/docs/doxygen/overviews/app.h
@@ -53,12 +53,9 @@ bool DerivedApp::OnInit()
 }
 @endcode
 
-Note the use of wxIMPLEMENT_APP(appClass), which allows wxWidgets to dynamically
-create an instance of the application object at the appropriate point in
-wxWidgets initialization. Previous versions of wxWidgets used to rely on the
-creation of a global application object, but this is no longer recommended,
-because required global initialization may not have been performed at
-application object construction time.
+Note the use of wxIMPLEMENT_APP(), which defines the application entry
+point (either @c main() or @c WinMain() function, depending on the platform)
+and tells wxWidgets which application class should be used.
 
 You can also use wxDECLARE_APP(appClass) in a header file to declare the wxGetApp
 function which returns a reference to the application object. Otherwise you can
diff --git a/interface/wx/app.h b/interface/wx/app.h
index 942b64aed8..0cad9adb6b 100644
--- a/interface/wx/app.h
+++ b/interface/wx/app.h
@@ -1132,8 +1132,17 @@ public:
 #define wxDECLARE_APP( className )
 
 /**
-    This is used in the application class implementation file to make the
-    application class known to wxWidgets for dynamic construction.
+    This macro defines the application entry point and tells wxWidgets which
+    application class should be used.
+
+    The two tasks performed by this macro can be done separately by using
+    wxIMPLEMENT_APP_NO_MAIN() and wxIMPLEMENT_WXWIN_MAIN() macros, but in a
+    typical GUI application it's simpler and more convenient to use this macro
+    to do both together.
+
+    The @a className passed to this macro must be a name of the class deriving
+    from wxApp.
+
     Note that this macro requires a final semicolon.
 
     @header{wx/app.h}
@@ -1148,6 +1157,24 @@ public:
 */
 #define wxIMPLEMENT_APP( className )
 
+/**
+    This macro defines the application entry point appropriate for the current
+    platform.
+
+    Note that usually wxIMPLEMENT_APP() is used instead of this macro.
+
+    For most platforms, it defines @c main() function, but for GUI Windows
+    applications, it defines @c WinMain() instead.
+
+    In either case, the macro expansion includes the call to
+    wxDISABLE_DEBUG_SUPPORT() which disables debugging code in release builds.
+    If you don't use this macro, but define the entry point yourself, you
+    probably want to call wxDISABLE_DEBUG_SUPPORT() explicitly.
+
+    @header{wx/app.h}
+ */
+#define wxIMPLEMENT_WXWIN_MAIN
+
 //@}