SDL: iostream: Final fixes before merging.

From b7cda16613d4f5e33e6ef5dca03ee3346fd4a1db Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 15 Mar 2024 15:34:29 -0400
Subject: [PATCH] iostream: Final fixes before merging.

- SDL_GetRWProperties -> SDL_GetIOProperties
- SDL_GetRWStatus -> SDL_GetIOStatus
- Some documentation corrections and improvements.
---
 include/SDL3/SDL_iostream.h       | 15 ++++++---------
 src/dynapi/SDL_dynapi.sym         |  4 ++--
 src/dynapi/SDL_dynapi_overrides.h |  4 ++--
 src/dynapi/SDL_dynapi_procs.h     |  4 ++--
 src/file/SDL_iostream.c           | 10 +++++-----
 5 files changed, 17 insertions(+), 20 deletions(-)

diff --git a/include/SDL3/SDL_iostream.h b/include/SDL3/SDL_iostream.h
index 2cba0ce3f05e5..c89b2e09e58c9 100644
--- a/include/SDL3/SDL_iostream.h
+++ b/include/SDL3/SDL_iostream.h
@@ -161,7 +161,7 @@ typedef struct SDL_IOStream SDL_IOStream;
  * As a fallback, SDL_IOFromFile() will transparently open a matching filename
  * in an Android app's `assets`.
  *
- * Destroying the SDL_IOStream will close the file handle SDL is holding internally.
+ * Closing the SDL_IOStream will close SDL's internal file handle.
  *
  * The following properties may be set at creation time by SDL:
  *
@@ -191,6 +191,7 @@ typedef struct SDL_IOStream SDL_IOStream;
  *
  * \sa SDL_IOFromConstMem
  * \sa SDL_IOFromMem
+ * \sa SDL_CloseIO
  * \sa SDL_ReadIO
  * \sa SDL_SeekIO
  * \sa SDL_TellIO
@@ -226,6 +227,7 @@ extern DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromFile(const char *file, const cha
  * \sa SDL_IOFromConstMem
  * \sa SDL_IOFromFile
  * \sa SDL_IOFromMem
+ * \sa SDL_CloseIO
  * \sa SDL_ReadIO
  * \sa SDL_SeekIO
  * \sa SDL_TellIO
@@ -259,6 +261,7 @@ extern DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromMem(void *mem, size_t size);
  * \sa SDL_IOFromConstMem
  * \sa SDL_IOFromFile
  * \sa SDL_IOFromMem
+ * \sa SDL_CloseIO
  * \sa SDL_ReadIO
  * \sa SDL_SeekIO
  * \sa SDL_TellIO
@@ -328,7 +331,7 @@ extern DECLSPEC int SDLCALL SDL_CloseIO(SDL_IOStream *context);
  * \sa SDL_GetProperty
  * \sa SDL_SetProperty
  */
-extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRWProperties(SDL_IOStream *context);
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context);
 
 #define SDL_IO_SEEK_SET 0       /**< Seek from the beginning of data */
 #define SDL_IO_SEEK_CUR 1       /**< Seek relative to current read point */
@@ -353,7 +356,7 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRWProperties(SDL_IOStream *conte
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC SDL_IOStatus SDLCALL SDL_GetRWStatus(SDL_IOStream *context);
+extern DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context);
 
 /**
  * Use this function to get the size of the data stream in an SDL_IOStream.
@@ -433,9 +436,6 @@ extern DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
  * that this is not an error or end-of-file, and the caller can try again
  * later.
  *
- * SDL_ReadIO() is actually a function wrapper that calls the SDL_IOStream's
- * `read` method appropriately, to simplify application development.
- *
  * \param context a pointer to an SDL_IOStream structure
  * \param ptr a pointer to a buffer to read data into
  * \param size the number of bytes to read from the data source.
@@ -465,9 +465,6 @@ extern DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, size
  * written because it would require blocking, this function returns -2 to
  * distinguish that this is not an error and the caller can try again later.
  *
- * SDL_WriteIO is actually a function wrapper that calls the SDL_IOStream's
- * `write` method appropriately, to simplify application development.
- *
  * It is an error to specify a negative `size`, but this parameter is signed
  * so you definitely cannot overflow the return value on a successful run with
  * enormous amounts of data.
diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym
index 38a1bc74260d9..e2e209be1e6aa 100644
--- a/src/dynapi/SDL_dynapi.sym
+++ b/src/dynapi/SDL_dynapi.sym
@@ -878,7 +878,7 @@ SDL3_0.0.0 {
     SDL_GetJoystickProperties;
     SDL_GetRendererProperties;
     SDL_GetTextureProperties;
-    SDL_GetRWProperties;
+    SDL_GetIOProperties;
     SDL_GetSensorProperties;
     SDL_GetSurfaceProperties;
     SDL_GetWindowProperties;
@@ -978,7 +978,7 @@ SDL3_0.0.0 {
     SDL_ShowOpenFolderDialog;
     SDL_OpenIO;
     SDL_CloseIO;
-    SDL_GetRWStatus;
+    SDL_GetIOStatus;
     # extra symbols go here (don't modify this line)
   local: *;
 };
diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h
index 1e0b94474a7ca..790bf10743bad 100644
--- a/src/dynapi/SDL_dynapi_overrides.h
+++ b/src/dynapi/SDL_dynapi_overrides.h
@@ -903,7 +903,7 @@
 #define SDL_GetJoystickProperties SDL_GetJoystickProperties_REAL
 #define SDL_GetRendererProperties SDL_GetRendererProperties_REAL
 #define SDL_GetTextureProperties SDL_GetTextureProperties_REAL
-#define SDL_GetRWProperties SDL_GetRWProperties_REAL
+#define SDL_GetIOProperties SDL_GetIOProperties_REAL
 #define SDL_GetSensorProperties SDL_GetSensorProperties_REAL
 #define SDL_GetSurfaceProperties SDL_GetSurfaceProperties_REAL
 #define SDL_GetWindowProperties SDL_GetWindowProperties_REAL
@@ -1003,4 +1003,4 @@
 #define SDL_ShowOpenFolderDialog SDL_ShowOpenFolderDialog_REAL
 #define SDL_OpenIO SDL_OpenIO_REAL
 #define SDL_CloseIO SDL_CloseIO_REAL
-#define SDL_GetRWStatus SDL_GetRWStatus_REAL
+#define SDL_GetIOStatus SDL_GetIOStatus_REAL
diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h
index 72010b411e3dc..83cc68d907c0d 100644
--- a/src/dynapi/SDL_dynapi_procs.h
+++ b/src/dynapi/SDL_dynapi_procs.h
@@ -937,7 +937,7 @@ SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetGamepadProperties,(SDL_Gamepad *a),(a),r
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetJoystickProperties,(SDL_Joystick *a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetRendererProperties,(SDL_Renderer *a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetTextureProperties,(SDL_Texture *a),(a),return)
-SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetRWProperties,(SDL_IOStream *a),(a),return)
+SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetIOProperties,(SDL_IOStream *a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetSensorProperties,(SDL_Sensor *a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetSurfaceProperties,(SDL_Surface *a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetWindowProperties,(SDL_Window *a),(a),return)
@@ -1028,4 +1028,4 @@ SDL_DYNAPI_PROC(void,SDL_ShowSaveFileDialog,(SDL_DialogFileCallback a, void *b,
 SDL_DYNAPI_PROC(void,SDL_ShowOpenFolderDialog,(SDL_DialogFileCallback a, void *b, SDL_Window *c, const char *d, int e),(a,b,c,d,e),)
 SDL_DYNAPI_PROC(SDL_IOStream*,SDL_OpenIO,(const SDL_IOStreamInterface *a, void *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_CloseIO,(SDL_IOStream *a),(a),return)
-SDL_DYNAPI_PROC(SDL_IOStatus,SDL_GetRWStatus,(SDL_IOStream *a),(a),return)
+SDL_DYNAPI_PROC(SDL_IOStatus,SDL_GetIOStatus,(SDL_IOStream *a),(a),return)
diff --git a/src/file/SDL_iostream.c b/src/file/SDL_iostream.c
index 88eef41ff5fbb..6562d0a5fa1f4 100644
--- a/src/file/SDL_iostream.c
+++ b/src/file/SDL_iostream.c
@@ -428,7 +428,7 @@ static SDL_IOStream *SDL_IOFromFP(FILE *fp, SDL_bool autoclose)
     if (!iostr) {
         iface.close(iodata);
     } else {
-        const SDL_PropertiesID props = SDL_GetRWProperties(iostr);
+        const SDL_PropertiesID props = SDL_GetIOProperties(iostr);
         if (props) {
             SDL_SetProperty(props, SDL_PROP_IOSTREAM_STDIO_HANDLE_POINTER, fp);
         }
@@ -587,7 +587,7 @@ SDL_IOStream *SDL_IOFromFile(const char *file, const char *mode)
     if (!iostr) {
         iface.close(iodata);
     } else {
-        const SDL_PropertiesID props = SDL_GetRWProperties(iostr);
+        const SDL_PropertiesID props = SDL_GetIOProperties(iostr);
         if (props) {
             SDL_SetProperty(props, SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER, iodata);
         }
@@ -619,7 +619,7 @@ SDL_IOStream *SDL_IOFromFile(const char *file, const char *mode)
     if (!iostr) {
         windows_file_close(iodata);
     } else {
-        const SDL_PropertiesID props = SDL_GetRWProperties(iostr);
+        const SDL_PropertiesID props = SDL_GetIOProperties(iostr);
         if (props) {
             SDL_SetProperty(props, SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER, iodata->h);
         }
@@ -724,7 +724,7 @@ SDL_IOStream *SDL_IOFromConstMem(const void *mem, size_t size)
     return iostr;
 }
 
-SDL_IOStatus SDL_GetRWStatus(SDL_IOStream *context)
+SDL_IOStatus SDL_GetIOStatus(SDL_IOStream *context)
 {
     if (!context) {
         SDL_InvalidParamError("context");
@@ -835,7 +835,7 @@ void *SDL_LoadFile(const char *file, size_t *datasize)
     return SDL_LoadFile_IO(SDL_IOFromFile(file, "rb"), datasize, SDL_TRUE);
 }
 
-SDL_PropertiesID SDL_GetRWProperties(SDL_IOStream *context)
+SDL_PropertiesID SDL_GetIOProperties(SDL_IOStream *context)
 {
     if (!context) {
         SDL_InvalidParamError("context");