From b2eb23a617d5a037507cd2f8b9fc37b32c8d2e25 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
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 af3eae2ac19ab..13234afde72bb 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.
*