From cf0b5db9e12b58b46148b1e4c5dc425ac21f6051 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Fri, 3 May 2024 15:37:11 -0400
Subject: [PATCH] SDL_system.h: Improve window message hook documentation.

---
 include/SDL3/SDL_system.h | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 2070d50cd6..2155ec88b4 100644
--- a/include/SDL3/SDL_system.h
+++ b/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);