From 7f9ee31024ed101367e5f4abfe76ef90e4ba6a05 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sun, 5 Jan 2025 14:11:11 -0500
Subject: [PATCH] include: Fill in more category documentation.
Reference Issue #11874.
---
include/SDL3/SDL_filesystem.h | 18 +++++++++++++++++-
include/SDL3/SDL_iostream.h | 2 +-
include/SDL3/SDL_metal.h | 4 ++++
include/SDL3/SDL_stdinc.h | 24 +++++++++++++++++++-----
include/SDL3/SDL_system.h | 8 +++++++-
5 files changed, 48 insertions(+), 8 deletions(-)
diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h
index 8bc2356e9f4cc..1624113a9191a 100644
--- a/include/SDL3/SDL_filesystem.h
+++ b/include/SDL3/SDL_filesystem.h
@@ -22,7 +22,23 @@
/**
* # CategoryFilesystem
*
- * SDL Filesystem API.
+ * SDL offers an API for examining and manipulating the system's filesystem.
+ * This covers most things one would need to do with directories, except for
+ * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream)
+ * and [CategoryAsyncIO](CategoryAsyncIO) instead).
+ *
+ * There are functions to answer necessary path questions:
+ *
+ * - Where is my app's data? SDL_GetBasePath().
+ * - Where can I safely write files? SDL_GetPrefPath().
+ * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder().
+ * - What is this thing at this location? SDL_GetPathInfo().
+ * - What items live in this folder? SDL_EnumerateDirectory().
+ * - What items live in this folder by wildcard? SDL_GlobDirectory().
+ * - What is my current working directory? SDL_GetCurrentDirectory().
+ *
+ * SDL also offers functions to manipulate the directory tree: renaming,
+ * removing, copying files.
*/
#ifndef SDL_filesystem_h_
diff --git a/include/SDL3/SDL_iostream.h b/include/SDL3/SDL_iostream.h
index b3210e3e8af4f..e0456c7c29d20 100644
--- a/include/SDL3/SDL_iostream.h
+++ b/include/SDL3/SDL_iostream.h
@@ -25,7 +25,7 @@
* # CategoryIOStream
*
* SDL provides an abstract interface for reading and writing data streams. It
- * offers implementations for files, memory, etc, and the app can provideo
+ * offers implementations for files, memory, etc, and the app can provide
* their own implementations, too.
*
* SDL_IOStream is not related to the standard C++ iostream class, other than
diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h
index 2d237683947f1..87d18dbfdc082 100644
--- a/include/SDL3/SDL_metal.h
+++ b/include/SDL3/SDL_metal.h
@@ -23,6 +23,10 @@
* # CategoryMetal
*
* Functions to creating Metal layers and views on SDL windows.
+ *
+ * This provides some platform-specific glue for Apple platforms. Most macOS
+ * and iOS apps can use SDL without these functions, but this API they can be
+ * useful for specific OS-level integration tasks.
*/
#ifndef SDL_metal_h_
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 72b636174a772..31f56f78013cd 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -22,11 +22,25 @@
/**
* # CategoryStdinc
*
- * This is a general header that includes C language support. It implements a
- * subset of the C runtime APIs, but with an `SDL_` prefix. For most common
- * use cases, these should behave the same way as their C runtime equivalents,
- * but they may differ in how or whether they handle certain edge cases. When
- * in doubt, consult the documentation for details.
+ * SDL provides its own implementation of some of the most important C runtime
+ * functions.
+ *
+ * Using these functions allows an app to have access to common C
+ * functionality without depending on a specific C runtime (or a C runtime at
+ * all). More importantly, the SDL implementations work identically across
+ * platforms, so apps can avoid surprises like snprintf() behaving differently
+ * between Windows and Linux builds, or itoa() only existing on some
+ * platforms.
+ *
+ * For many of the most common functions, like SDL_memcpy, SDL might just
+ * call through to the usual C runtime behind the scenes, if it makes sense to
+ * do so (if it's faster and always available/reliable on a given platform),
+ * reducing library size and offering the most optimized option.
+ *
+ * SDL also offers other C-runtime-adjacent functionality in this header that
+ * either isn't, strictly speaking, part of any C runtime standards, like
+ * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better
+ * options, like SDL_strlcpy(), which functions as a safer form of strcpy().
*/
#ifndef SDL_stdinc_h_
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 54fe3d6b28e69..b59c42016a70e 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -22,7 +22,13 @@
/**
* # CategorySystem
*
- * Platform-specific SDL API functions.
+ * Platform-specific SDL API functions. These are functions that deal with
+ * needs of specific operating systems, that didn't make sense to offer as
+ * platform-independent, generic APIs.
+ *
+ * Most apps can make do without these functions, but they can be useful for
+ * integrating with other parts of a specific system, adding platform-specific
+ * polish to an app, or solving problems that only affect one target.
*/
#ifndef SDL_system_h_