include: More category documentation.

Reference Issue #11847.

Author: icculus

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>

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>