From 0fe99004291f3706b3d82475b5fc1b57c267ed5c Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 27 May 2024 12:58:22 -0400
Subject: [PATCH] main: Main callback docs recommend returning the symbols
instead of -1, 0, 1.
Reference #9901.
---
include/SDL3/SDL_main.h | 53 ++++++++++++++++++++++++-----------------
1 file changed, 31 insertions(+), 22 deletions(-)
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index 73963dd128d04..028c4810d71ea 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -277,20 +277,23 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
* to use a global variable. If this isn't set, the pointer will be NULL in
* future entry points.
*
- * If this function returns 0, the app will proceed to normal operation, and
- * will begin receiving repeated calls to SDL_AppIterate and SDL_AppEvent for
- * the life of the program. If this function returns < 0, SDL will call
+ * If this function returns SDL_MAIN_CALLBACK_CONTINUE, the app will proceed
+ * to normal operation, and will begin receiving repeated calls to
+ * SDL_AppIterate and SDL_AppEvent for the life of the program. If this
+ * function returns SDL_MAIN_CALLBACK_EXIT_FAILURE, SDL will call
* SDL_AppQuit and terminate the process with an exit code that reports an
- * error to the platform. If it returns > 0, the SDL calls SDL_AppQuit and
- * terminates with an exit code that reports success to the platform.
+ * error to the platform. If it returns SDL_MAIN_CALLBACK_EXIT_SUCCESS, SDL
+ * calls SDL_AppQuit and terminates with an exit code that reports success to
+ * the platform.
*
* \param appstate a place where the app can optionally store a pointer for
* future use.
* \param argc The standard ANSI C main's argc; number of elements in `argv`
* \param argv The standard ANSI C main's argv; array of command line
* arguments.
- * \returns -1 to terminate with an error, 1 to terminate with success, 0 to
- * continue.
+ * \returns SDL_MAIN_CALLBACK_EXIT_FAILURE to terminate with an error,
+ * SDL_MAIN_CALLBACK_EXIT_SUCCESS to terminate with success,
+ * SDL_MAIN_CALLBACK_CONTINUE to continue.
*
* \threadsafety This function is not thread safe.
*
@@ -329,16 +332,20 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char
* The `appstate` parameter is an optional pointer provided by the app during
* SDL_AppInit(). If the app never provided a pointer, this will be NULL.
*
- * If this function returns 0, the app will continue normal operation,
- * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of
- * the program. If this function returns < 0, SDL will call SDL_AppQuit and
+ * If this function returns SDL_MAIN_CALLBACK_CONTINUE, the app will continue
+ * normal operation, receiving repeated calls to SDL_AppIterate and
+ * SDL_AppEvent for the life of the program. If this function returns
+ * SDL_MAIN_CALLBACK_EXIT_FAILURE, SDL will call SDL_AppQuit and
* terminate the process with an exit code that reports an error to the
- * platform. If it returns > 0, the SDL calls SDL_AppQuit and terminates with
- * an exit code that reports success to the platform.
+ * platform. If it returns SDL_MAIN_CALLBACK_EXIT_SUCCESS, SDL calls
+ * SDL_AppQuit and terminates with an exit code that reports success to the
+ * platform.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
- * \returns -1 to terminate with an error, 1 to terminate with success, 0 to
- * continue.
+ * \returns SDL_MAIN_CALLBACK_EXIT_FAILURE to terminate with an error,
+ * SDL_MAIN_CALLBACK_EXIT_SUCCESS to terminate with success,
+ * SDL_MAIN_CALLBACK_CONTINUE to continue.
+ *
*
* \threadsafety This function is not thread safe.
*
@@ -374,17 +381,19 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void *appstate);
* The `appstate` parameter is an optional pointer provided by the app during
* SDL_AppInit(). If the app never provided a pointer, this will be NULL.
*
- * If this function returns 0, the app will continue normal operation,
- * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of
- * the program. If this function returns < 0, SDL will call SDL_AppQuit and
- * terminate the process with an exit code that reports an error to the
- * platform. If it returns > 0, the SDL calls SDL_AppQuit and terminates with
- * an exit code that reports success to the platform.
+ * If this function returns SDL_MAIN_CALLBACK_CONTINUE, the app will continue
+ * normal operation, receiving repeated calls to SDL_AppIterate and
+ * SDL_AppEvent for the life of the program. If this function returns
+ * SDL_MAIN_CALLBACK_EXIT_FAILURE, SDL will call SDL_AppQuit and terminate the
+ * process with an exit code that reports an error to the platform. If it
+ * returns SDL_MAIN_CALLBACK_EXIT_SUCCESS, SDL calls SDL_AppQuit and
+ * terminates with an exit code that reports success to the platform.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
* \param event the new event for the app to examine.
- * \returns -1 to terminate with an error, 1 to terminate with success, 0 to
- * continue.
+ * \returns SDL_MAIN_CALLBACK_EXIT_FAILURE to terminate with an error,
+ * SDL_MAIN_CALLBACK_EXIT_SUCCESS to terminate with success,
+ * SDL_MAIN_CALLBACK_CONTINUE to continue.
*
* \threadsafety This function is not thread safe.
*