Finished review of Application Initialization and Termination category of functions and macros.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52601 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/app.h

@@ -608,14 +608,6 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/**
-    The global pointer to the singleton wxApp object.
-
-    @see wxApp::GetInstance()
-*/
-wxApp *wxTheApp;
-
-
 
 /** @ingroup group_funcmacro_rtti */
 //@{
@@ -656,41 +648,49 @@ wxApp *wxTheApp;
 
 
 
+/**
+    The global pointer to the singleton wxApp object.
+
+    @see wxApp::GetInstance()
+*/
+wxApp *wxTheApp;
+
+
+
 /** @ingroup group_funcmacro_appinitterm */
 //@{
 
 /**
-    This function doesn't exist in wxWidgets but it is created by using
-    the IMPLEMENT_APP() macro.
+    This function doesn't exist in wxWidgets but it is created by using the
+    IMPLEMENT_APP() macro.
 
     Thus, before using it anywhere but in the same module where this macro is
     used, you must make it available using DECLARE_APP().
 
     The advantage of using this function compared to directly using the global
-    wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
-    allow you to access the functions specific to your application class but not
-    present in wxApp while wxGetApp() returns the object of the right type.
+    ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
+    allow you to access the functions specific to your application class but
+    not present in wxApp while wxGetApp() returns the object of the right type.
 */
-wxAppDerivedClass wxGetApp();
+wxAppDerivedClass& wxGetApp();
 
 /**
     If @a doIt is @true, the fatal exceptions (also known as general protection
     faults under Windows or segmentation violations in the Unix world) will be
     caught and passed to wxApp::OnFatalException.
 
-    By default, i.e. before this function is called, they will be handled in the
-    normal way which usually just means that the application will be terminated.
-    Calling wxHandleFatalExceptions() with @a doIt equal to @false will restore
-    this default behaviour.
+    By default, i.e. before this function is called, they will be handled in
+    the normal way which usually just means that the application will be
+    terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false
+    will restore this default behaviour.
 
-    Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION is 1
-    and under Windows platform this requires a compiler with support for SEH
-    (structured exception handling) which currently means only Microsoft Visual C++
-    or a recent Borland C++ version.
+    Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION
+    is 1 and under Windows platform this requires a compiler with support for
+    SEH (structured exception handling) which currently means only Microsoft
+    Visual C++ or a recent Borland C++ version.
 */
 bool wxHandleFatalExceptions(bool doIt = true);
 
-
 /**
     This function is used in wxBase only and only if you don't create
     wxApp object at all. In this case you must call it from your
@@ -711,6 +711,16 @@ bool wxInitialize();
 */
 void wxUninitialize();
 
+/**
+    This function wakes up the (internal and platform dependent) idle system,
+    i.e. it will force the system to send an idle event even if the system
+    currently @e is idle and thus would not send any idle event until after
+    some other event would get sent. This is also useful for sending events
+    between two threads and is used by the corresponding functions
+    wxPostEvent() and wxEvtHandler::AddPendingEvent().
+*/
+void wxWakeUpIdle();
+
 /**
     Calls wxApp::Yield.
 

interface/image.h

@@ -1467,6 +1467,9 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_appinitterm */
+//@{
+
 /**
     Initializes all available image handlers. For a list of available handlers,
     see wxImage.
@@ -1475,3 +1478,5 @@ public:
 */
 void wxInitAllImageHandlers();
 
+//@}
+

interface/init.h

@@ -6,22 +6,42 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
-/**
-Free resources allocated by a successful call to wxEntryStart().
-*/
-void wxEntryCleanup();
-
-
+/** @ingroup group_funcmacro_appinitterm */
 //@{
+
 /**
-    (notice that under Windows CE platform, and only there, the type of
-    @a pCmdLine is @c wchar_t *, otherwise it is @c char *, even in
-    Unicode build).
+    This function can be used to perform the initialization of wxWidgets if you
+    can't use the default initialization code for any reason.
+
+    If the function returns true, the initialization was successful and the
+    global wxApp object ::wxTheApp has been created. Moreover, wxEntryCleanup()
+    must be called afterwards. If the function returns false, a catastrophic
+    initialization error occured and (at least the GUI part of) the library
+    can't be used at all.
+
+    Notice that parameters @c argc and @c argv may be modified by this
+    function.
 */
 bool wxEntryStart(int& argc, wxChar** argv);
+
+/**
+    See wxEntryStart(int&,wxChar**) for more info about this function.
+
+    This is an additional overload of wxEntryStart() provided under MSW only.
+    It is meant to be called with the parameters passed to WinMain().
+
+    @note Under Windows CE platform, and only there, the type of @a pCmdLine is
+    @c wchar_t *, otherwise it is @c char *, even in Unicode build.
+*/
 bool wxEntryStart(HINSTANCE hInstance,
                   HINSTANCE hPrevInstance = NULL,
                   char* pCmdLine = NULL,
                   int nCmdShow = SW_SHOWNORMAL);
+
+/**
+    Free resources allocated by a successful call to wxEntryStart().
+*/
+void wxEntryCleanup();
+
 //@}