SDL_system.h: Improve window message hook documentation.

include/SDL3/SDL_system.h

@@ -47,6 +47,28 @@ extern "C" {
 #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)
 
 typedef struct tagMSG MSG;
+
+/**
+ * A callback to be used with SDL_SetWindowsMessageHook.
+ *
+ * This callback may modify the message, and should return SDL_TRUE
+ * if the message should continue to be processed, or SDL_FALSE
+ * to prevent further processing.
+ *
+ * As this is processing a message directly from the Windows event loop,
+ * this callback should do the minimum required work and return quickly.
+ *
+ * \param userdata the app-defined pointer provided to SDL_SetWindowsMessageHook.
+ * \param msg a pointer to a Win32 event structure to process.
+ * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it.
+ *
+ * \threadsafety This may only be called (by SDL) from the thread handling the Windows event loop.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetWindowsMessageHook
+ * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
+ */
 typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
 
 /**
@@ -60,6 +82,9 @@ typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
  * \param userdata a pointer to pass to every iteration of `callback`
  *
  * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_WindowsMessageHook
+ * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
  */
 extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);