Heavy work on improving category documentation.

Still more to go!

Reference Issue #9440.

include/SDL3/SDL_begin_code.h

@@ -25,6 +25,9 @@
  * SDL_begin_code.h sets things up for C dynamic library function definitions,
  * static inlined functions, and structures aligned at 4-byte alignment.
  * If you don't like ugly C preprocessor code, don't look at this file. :)
+ *
+ * SDL's headers use this; applications generally should not include this
+ * header directly.
  */
 
 /* This shouldn't be nested -- included it around code only. */