include: More category documentation.

Reference Issue #11847.

Author: icculus

include/SDL3/SDL_time.h

@@ -26,6 +26,14 @@ freely, subject to the following restrictions:
  * # CategoryTime
  *
  * SDL realtime clock and date/time routines.
+ *
+ * There are two data types that are used in this category: SDL_Time, which
+ * represents the nanoseconds since a specific moment (an "epoch"), and
+ * SDL_DateTime, which breaks time down into human-understandable components:
+ * years, months, days, hours, etc.
+ *
+ * Much of the functionality is involved in converting those two types to
+ * other useful forms.
  */
 
 #include <SDL3/SDL_error.h>

include/SDL3/SDL_touch.h

@@ -22,7 +22,18 @@
 /**
  * # CategoryTouch
  *
- * SDL touch management.
+ * SDL offers touch input, on platforms that support it. It can manage
+ * multiple touch devices and track multiple fingers on those devices.
+ *
+ * Touches are mostly dealt with through the event system, in the
+ * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP
+ * events, but there are also functions to query for hardware details, etc.
+ *
+ * The touch system, by default, will also send virtual mouse events; this can
+ * be useful for making a some desktop apps work on a phone without
+ * significant changes. For apps that care about mouse and touch input
+ * separately, they should ignore mouse events that have a `which` field of
+ * SDL_TOUCH_MOUSEID.
  */
 
 #ifndef SDL_touch_h_

include/SDL3/SDL_tray.h

@@ -22,7 +22,11 @@
 /**
  * # CategoryTray
  *
- * System tray menu support.
+ * SDL offers a way to add items to the "system tray" (more correctly called
+ * the "notification area" on Windows). On platforms that offer this concept,
+ * an SDL app can add a tray icon, submenus, checkboxes, and clickable
+ * entries, and register a callback that is fired when the user clicks on
+ * these pieces.
  */
 
 #ifndef SDL_tray_h_