From 2be749b23badd95393e5c53050e609c17181dd15 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 20 Jan 2025 01:37:25 -0500
Subject: [PATCH] include: More category documentation.
Reference Issue #11847.
---
include/SDL3/SDL_mutex.h | 14 +++++++++++++-
include/SDL3/SDL_thread.h | 14 +++++++++++++-
2 files changed, 26 insertions(+), 2 deletions(-)
diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
index 8e2c8651b4bf3..b60d8421a7eea 100644
--- a/include/SDL3/SDL_mutex.h
+++ b/include/SDL3/SDL_mutex.h
@@ -25,7 +25,19 @@
/**
* # CategoryMutex
*
- * Functions to provide thread synchronization primitives.
+ * SDL offers several thread synchronization primitives. This document can't
+ * cover the complicated topic of thread safety, but reading up on what each
+ * of these primitives are, why they are useful, and how to correctly use them
+ * is vital to writing correct and safe multithreaded programs.
+ *
+ * - Mutexes: SDL_CreateMutex()
+ * - Read/Write locks: SDL_CreateRWLock()
+ * - Semaphores: SDL_CreateSemaphore()
+ * - Condition variables: SDL_CreateCondition()
+ *
+ * SDL also offers a datatype, SDL_InitState, which can be used to make sure
+ * only one thread initializes/deinitializes some resource that several
+ * threads might try to use for the first time simultaneously.
*/
#include <SDL3/SDL_stdinc.h>
diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h
index d7d83edb51dcd..240812db1717e 100644
--- a/include/SDL3/SDL_thread.h
+++ b/include/SDL3/SDL_thread.h
@@ -25,7 +25,19 @@
/**
* # CategoryThread
*
- * SDL thread management routines.
+ * SDL offers cross-platform thread management functions. These are mostly
+ * concerned with starting threads, setting their priority, and dealing with
+ * their termination.
+ *
+ * In addition, there is support for Thread Local Storage (data that is unique
+ * to each thread, but accessed from a single key).
+ *
+ * On platforms without thread support (such as Emscripten when built without
+ * pthreads), these functions still exist, but things like SDL_CreateThread()
+ * will report failure without doing anything.
+ *
+ * If you're going to work with threads, you almost certainly need to have a
+ * good understanding of [CategoryMutex](CategoryMutex) as well.
*/
#include <SDL3/SDL_stdinc.h>