From d5766bc4b83afa0891e142c0b8b3dc694f3da579 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 20 Jan 2025 00:39:02 -0500
Subject: [PATCH] include: More category documentation.
Reference Issue #11847.
---
include/SDL3/SDL_time.h | 8 ++++++++
include/SDL3/SDL_touch.h | 13 ++++++++++++-
include/SDL3/SDL_tray.h | 6 +++++-
3 files changed, 25 insertions(+), 2 deletions(-)
diff --git a/include/SDL3/SDL_time.h b/include/SDL3/SDL_time.h
index c1880dce7ee33..cc611984de56f 100644
--- a/include/SDL3/SDL_time.h
+++ b/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>
diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h
index 0f32e11eb7218..1260f573d2f18 100644
--- a/include/SDL3/SDL_touch.h
+++ b/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_
diff --git a/include/SDL3/SDL_tray.h b/include/SDL3/SDL_tray.h
index ba96c3f6f206d..83bd3b787c632 100644
--- a/include/SDL3/SDL_tray.h
+++ b/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_