SDL: Update documentation to reflect that a single SDL_PumpEvents() each frame is the recommended way to handle events

SDL Commits
1 
From ddf1d5c55327045a84a0cd04c840e2eef87a5670 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Thu, 14 Oct 2021 19:10:30 -0700
Subject: [PATCH] Update documentation to reflect that a single
 SDL_PumpEvents() each frame is the recommended way to handle events

---
 include/SDL_events.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/include/SDL_events.h b/include/SDL_events.h
index c3037b26dd..c1e28f7771 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -801,9 +801,8 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
  * As this function implicitly calls SDL_PumpEvents(), you can only call this
  * function in the thread that set the video mode.
  *
- * SDL_PollEvent() is the favored way of receiving system events since it can
- * be done from the main loop and does not suspend the main loop while waiting
- * on an event to be posted.
+ * SDL_PollEvent() is deprecated as some sensors and mice with extremely high
+ * update rates can generate events each time this function is called.
  *
  * The common practice is to fully process the event queue once every frame,
  * usually as a first step before updating the game's state:
@@ -811,7 +810,8 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
  * ```c
  * while (game_is_still_running) {
  *     SDL_Event event;
- *     while (SDL_PollEvent(&event)) {  // poll until all events are handled!
+ *     SDL_PumpEvents();
+ *     while (SDL_PeepEvents(&event, 1, SDL_GETEVENT, 0, SDL_LASTEVENT) == 1) {  // poll until all events are handled!
  *         // decide what to do with this event.
  *     }
  *