From b2eb23a617d5a037507cd2f8b9fc37b32c8d2e25 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Fri, 20 Dec 2024 02:36:16 -0500
Subject: [PATCH] SDL_filesystem.h: Fill in missing documentation.

---
 include/SDL3/SDL_filesystem.h | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h
index af3eae2ac1..13234afde7 100644
--- a/include/SDL3/SDL_filesystem.h
+++ b/include/SDL3/SDL_filesystem.h
@@ -166,29 +166,17 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char *
 typedef enum SDL_Folder
 {
     SDL_FOLDER_HOME,        /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */
-
     SDL_FOLDER_DESKTOP,     /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */
-
     SDL_FOLDER_DOCUMENTS,   /**< User document files, possibly application-specific. This is a good place to save a user's projects. */
-
     SDL_FOLDER_DOWNLOADS,   /**< Standard folder for user files downloaded from the internet. */
-
     SDL_FOLDER_MUSIC,       /**< Music files that can be played using a standard music player (mp3, ogg...). */
-
     SDL_FOLDER_PICTURES,    /**< Image files that can be displayed using a standard viewer (png, jpg...). */
-
     SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */
-
     SDL_FOLDER_SAVEDGAMES,  /**< Save files for games. */
-
     SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */
-
     SDL_FOLDER_TEMPLATES,   /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt".  Any file in the Templates folder can be used as a starting point for a new file. */
-
     SDL_FOLDER_VIDEOS,      /**< Video files that can be played using a standard video player (mp4, webm...). */
-
     SDL_FOLDER_COUNT        /**< Total number of types in this enum, not a folder type by itself. */
-
 } SDL_Folder;
 
 /**
@@ -219,6 +207,17 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder);
 
 /* Abstract filesystem interface */
 
+/**
+ * Types of filesystem entries.
+ *
+ * Note that there may be other sorts of items on a filesystem: devices,
+ * symlinks, named pipes, etc. They are currently reported as
+ * SDL_PATHTYPE_OTHER.
+ *
+ * \since This enum is available since SDL 3.1.3.
+ *
+ * \sa SDL_PathInfo
+ */
 typedef enum SDL_PathType
 {
     SDL_PATHTYPE_NONE,      /**< path does not exist */
@@ -227,6 +226,14 @@ typedef enum SDL_PathType
     SDL_PATHTYPE_OTHER      /**< something completely different like a device node (not a symlink, those are always followed) */
 } SDL_PathType;
 
+/**
+ * Information about a path on the filesystem.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ *
+ * \sa SDL_GetPathInfo
+ * \sa SDL_GetStoragePathInfo
+ */
 typedef struct SDL_PathInfo
 {
     SDL_PathType type;      /**< the path type */
@@ -237,7 +244,7 @@ typedef struct SDL_PathInfo
 } SDL_PathInfo;
 
 /**
- * Flags for path matching
+ * Flags for path matching.
  *
  * \since This datatype is available since SDL 3.1.3.
  *