SDL: video: Document that SDL_RaiseWindow is a request and subject to window manager policy

From fbb5652d3ec5f04175c458442fc231857dab8e23 Mon Sep 17 00:00:00 2001
From: Frank Praznik <[EMAIL REDACTED]>
Date: Sat, 6 Jul 2024 11:45:04 -0400
Subject: [PATCH] video: Document that SDL_RaiseWindow is a request and subject
 to window manager policy

The result of SDL_RaiseWindow is ultimately subject to window manager policy, particularly if the request would result in stealing focus from another window. Document that this is only a request, and if successful, will result in a focus gained event along with the input focus flag being set on the window.
---
 include/SDL3/SDL_video.h | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index d536396102978..ee85f44ee7c15 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -1709,7 +1709,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_ShowWindow(SDL_Window *window);
 extern SDL_DECLSPEC int SDLCALL SDL_HideWindow(SDL_Window *window);
 
 /**
- * Raise a window above other windows and set the input focus.
+ * Request that a window be raised above other windows and gain the input focus.
+ *
+ * The result of this request is subject to desktop window manager policy,
+ * particularly if raising the requested window would result in stealing focus
+ * from another application. If the window is successfully raised and gains input
+ * focus, an SDL_EVENT_WINDOW_FOCUS_GAINED event will be emitted, and the window
+ * will have the SDL_WINDOW_INPUT_FOCUS flag set.
  *
  * \param window the window to raise.
  * \returns 0 on success or a negative error code on failure; call