Sync SDL3 wiki -> header

include/SDL3/SDL_main.h

@@ -194,34 +194,37 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
 /**
  * App-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps.
  *
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
- * using a standard "main" function, you should not supply this.
+ * standard "main" function, you should not supply this.
  *
  * This function is called by SDL once, at startup. The function should
- * initialize whatever is necessary, possibly create windows and open
+ * initialize whatever is necessary, possibly create windows and open audio
- * audio devices, etc. The `argc` and `argv` parameters work like they would
+ * devices, etc. The `argc` and `argv` parameters work like they would with a
- * with a standard "main" function.
+ * standard "main" function.
  *
  * This function should not go into an infinite mainloop; it should do any
  * one-time setup it requires and then return.
  *
  * The app may optionally assign a pointer to `*appstate`. This pointer will
  * be provided on every future call to the other entry points, to allow
- * application state to be preserved between functions without the app
+ * application state to be preserved between functions without the app needing
- * needing to use a global variable. If this isn't set, the pointer will
+ * to use a global variable. If this isn't set, the pointer will be NULL in
- * be NULL in future entry points.
+ * future entry points.
  *
- * If this function returns 0, the app will proceed to normal operation,
+ * If this function returns 0, the app will proceed to normal operation, and
- * and will begin receiving repeated calls to SDL_AppIterate and SDL_AppEvent
+ * will begin receiving repeated calls to SDL_AppIterate and SDL_AppEvent for
- * for the life of the program. If this function returns < 0, SDL will
+ * the life of the program. If this function returns < 0, SDL will call
- * call SDL_AppQuit and terminate the process with an exit code that reports
+ * SDL_AppQuit and terminate the process with an exit code that reports an
- * an error to the platform. If it returns > 0, the SDL calls SDL_AppQuit
+ * error to the platform. If it returns > 0, the SDL calls SDL_AppQuit and
- * and terminates with an exit code that reports success to the platform.
+ * 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 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.
+ * \param argv The standard ANSI C main's argv; array of command line
- * \returns -1 to terminate with an error, 1 to terminate with success, 0 to continue.
+ *             arguments.
+ * \returns -1 to terminate with an error, 1 to terminate with success, 0 to
+ *          continue.
  *
  * \threadsafety This function is not thread safe.
  *
@@ -236,23 +239,23 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char
 /**
  * App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps.
  *
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
- * using a standard "main" function, you should not supply this.
+ * standard "main" function, you should not supply this.
  *
- * This function is called repeatedly by SDL after SDL_AppInit returns 0.
+ * This function is called repeatedly by SDL after SDL_AppInit returns 0. The
- * The function should operate as a single iteration the program's primary
+ * function should operate as a single iteration the program's primary loop;
- * loop; it should update whatever state it needs and draw a new frame of
+ * it should update whatever state it needs and draw a new frame of video,
- * video, usually.
+ * usually.
  *
- * On some platforms, this function will be called at the refresh rate of
+ * On some platforms, this function will be called at the refresh rate of the
- * the display (which might change during the life of your app!). There are
+ * display (which might change during the life of your app!). There are no
- * no promises made about what frequency this function might run at. You
+ * promises made about what frequency this function might run at. You should
- * should use SDL's timer functions if you need to see how much time has
+ * use SDL's timer functions if you need to see how much time has passed since
- * passed since the last iteration.
+ * the last iteration.
  *
- * There is no need to process the SDL event queue during this function;
+ * There is no need to process the SDL event queue during this function; SDL
- * SDL will send events as they arrive in SDL_AppEvent, and in most cases
+ * will send events as they arrive in SDL_AppEvent, and in most cases the
- * the event queue will be empty when this function runs anyhow.
+ * event queue will be empty when this function runs anyhow.
  *
  * This function should not go into an infinite mainloop; it should do one
  * iteration of whatever the program does and return.
@@ -261,14 +264,15 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char
  * 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
+ * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of
- * of the program. If this function returns < 0, SDL will call SDL_AppQuit
+ * the program. If this function returns < 0, SDL will call SDL_AppQuit and
- * and terminate the process with an exit code that reports an error to the
+ * 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.
  *
  * \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 -1 to terminate with an error, 1 to terminate with success, 0 to
+ *          continue.
  *
  * \threadsafety This function is not thread safe.
  *
@@ -282,43 +286,44 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void *appstate);
 /**
  * App-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps.
  *
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
- * using a standard "main" function, you should not supply this.
+ * standard "main" function, you should not supply this.
  *
- * This function is called as needed by SDL after SDL_AppInit returns 0;
+ * This function is called as needed by SDL after SDL_AppInit returns 0; It is
- * It is called once for each new event.
+ * called once for each new event.
  *
  * There is (currently) no guarantee about what thread this will be called
  * from; whatever thread pushes an event onto SDL's queue will trigger this
- * function. SDL is responsible for pumping the event queue between
+ * function. SDL is responsible for pumping the event queue between each call
- * each call to SDL_AppIterate, so in normal operation one should only
+ * to SDL_AppIterate, so in normal operation one should only get events in a
- * get events in a serial fashion, but be careful if you have a thread that
+ * serial fashion, but be careful if you have a thread that explicitly calls
- * explicitly calls SDL_PushEvent.
+ * SDL_PushEvent.
  *
- * Events sent to this function are not owned by the app; if you need to
+ * Events sent to this function are not owned by the app; if you need to save
- * save the data, you should copy it.
+ * the data, you should copy it.
  *
  * You do not need to free event data (such as the `file` string in
- * SDL_EVENT_DROP_FILE), as SDL will free it once this function returns.
+ * SDL_EVENT_DROP_FILE), as SDL will free it once this function returns. Note
- * Note that this is different than one might expect when using a standard
+ * that this is different than one might expect when using a standard "main"
- * "main" function!
+ * function!
  *
- * This function should not go into an infinite mainloop; it should handle
+ * This function should not go into an infinite mainloop; it should handle the
- * the provided event appropriately and return.
+ * provided event appropriately and return.
  *
  * 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
+ * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of
- * of the program. If this function returns < 0, SDL will call SDL_AppQuit
+ * the program. If this function returns < 0, SDL will call SDL_AppQuit and
- * and terminate the process with an exit code that reports an error to the
+ * 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.
  *
  * \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 -1 to terminate with an error, 1 to terminate with success, 0 to
+ *          continue.
  *
  * \threadsafety This function is not thread safe.
  *
@@ -332,26 +337,26 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(void *appstate, const SDL_Event
 /**
  * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps.
  *
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
- * using a standard "main" function, you should not supply this.
+ * standard "main" function, you should not supply this.
  *
  * This function is called once by SDL before terminating the program.
  *
- * This function will be called no matter what, even if SDL_AppInit
+ * This function will be called no matter what, even if SDL_AppInit requests
- * requests termination.
+ * termination.
  *
  * This function should not go into an infinite mainloop; it should
- * deinitialize any resources necessary, perform whatever shutdown
+ * deinitialize any resources necessary, perform whatever shutdown activities,
- * activities, and return.
+ * and return.
  *
- * You do not need to call SDL_Quit() in this function, as SDL will call
+ * You do not need to call SDL_Quit() in this function, as SDL will call it
- * it after this function returns and before the process terminates, but
+ * after this function returns and before the process terminates, but it is
- * it is safe to do so.
+ * safe to do so.
  *
  * 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.
+ * SDL_AppInit(). If the app never provided a pointer, this will be NULL. This
- * This function call is the last time this pointer will be provided, so
+ * function call is the last time this pointer will be provided, so any
- * any resources to it should be cleaned up here.
+ * resources to it should be cleaned up here.
  *
  * \param appstate an optional pointer, provided by the app in SDL_AppInit.
  *