include: Fill in more category documentation.

Reference Issue #11874.

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_

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

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_

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_

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_