Heavy work on improving category documentation.

Still more to go!

Reference Issue #9440.

include/SDL3/SDL.h

@@ -20,9 +20,12 @@
 */
 
 /**
- *  \file SDL.h
+ * Main include header for the SDL library, version 3.1.7
  *
- *  Main include header for the SDL library, version 3.1.7
+ * It is almost always best to include just this one header instead of
+ * picking out individual headers included here. There are exceptions to
+ * this rule--SDL_main.h is special and not included here--but usually
+ * letting SDL.h include the kitchen sink for you is the correct approach.
  */
 
 #ifndef SDL_h_