Heavy work on improving category documentation.

Still more to go!

Reference Issue #9440.

include/SDL3/SDL_locale.h

@@ -23,6 +23,12 @@
  * # CategoryLocale
  *
  * SDL locale services.
+ *
+ * This provides a way to get a list of preferred locales (language plus
+ * country) for the user. There is exactly one function:
+ * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers
+ * documentation on all the strange ways humans might have configured their
+ * language settings.
  */
 
 #ifndef SDL_locale_h