From 81c94a165caed2a47d36ec55f53152dec38d6926 Mon Sep 17 00:00:00 2001
From: Sylvain <[EMAIL REDACTED]>
Date: Sun, 12 Feb 2023 20:39:22 +0100
Subject: [PATCH] Add \since docs where missing and resets some to 3.0.0 -
remove a \returns
---
include/SDL3/SDL_assert.h | 2 ++
include/SDL3/SDL_atomic.h | 4 ++++
include/SDL3/SDL_error.h | 2 ++
include/SDL3/SDL_rect.h | 6 ++++--
include/SDL3/SDL_stdinc.h | 4 ++--
include/SDL3/SDL_surface.h | 2 ++
include/SDL3/SDL_system.h | 28 ++++++++++++++++++++++++++++
include/SDL3/SDL_test_font.h | 12 ++++++------
include/SDL3/SDL_thread.h | 4 ++++
include/SDL3/SDL_video.h | 2 --
10 files changed, 54 insertions(+), 12 deletions(-)
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index 90def7b3d72f..3846a37d228b 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -138,6 +138,8 @@ typedef struct SDL_AssertData
* \param file file name
* \param line line number
* \returns assert state
+ *
+ * \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data,
const char *func,
diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h
index ad7098161dc8..02069569db61 100644
--- a/include/SDL3/SDL_atomic.h
+++ b/include/SDL3/SDL_atomic.h
@@ -186,6 +186,10 @@ extern __inline void SDL_CompilerBarrier(void);
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
+
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h
index 0492eaf4a760..1658f2fc238c 100644
--- a/include/SDL3/SDL_error.h
+++ b/include/SDL3/SDL_error.h
@@ -153,6 +153,8 @@ typedef enum
*
* \param code Error code
* \returns unconditionally -1.
+ *
+ * \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_Error(SDL_errorcode code);
/* @} *//* Internal error functions */
diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h
index 7d93d17847dd..1b5ce0410fc9 100644
--- a/include/SDL3/SDL_rect.h
+++ b/include/SDL3/SDL_rect.h
@@ -240,6 +240,8 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR
/**
* Returns true if the rectangle has no area.
+ *
+ * \since This function is available since SDL 3.0.0.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r)
{
@@ -249,7 +251,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r)
/**
* Returns true if the two rectangles are equal, within some given epsilon.
*
- * \since This function is available since SDL 2.0.22.
+ * \since This function is available since SDL 3.0.0.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
{
@@ -264,7 +266,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR
/**
* Returns true if the two rectangles are equal, using a default epsilon.
*
- * \since This function is available since SDL 2.0.22.
+ * \since This function is available since SDL 3.0.0.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b)
{
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 7e0dc66b44d9..1412800a9da7 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -732,7 +732,7 @@ SDL_FORCE_INLINE void *SDL_memcpy4(SDL_OUT_BYTECAP(dwords*4) void *dst, SDL_IN_B
* If a * b would overflow, return -1. Otherwise store a * b via ret
* and return 0.
*
- * \since This function is available since SDL 2.24.0.
+ * \since This function is available since SDL 3.0.0.
*/
SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a,
size_t b,
@@ -762,7 +762,7 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a,
* If a + b would overflow, return -1. Otherwise store a + b via ret
* and return 0.
*
- * \since This function is available since SDL 2.24.0.
+ * \since This function is available since SDL 3.0.0.
*/
SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a,
size_t b,
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 57a875401397..5d3836456fce 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -548,6 +548,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface,
* \param surface the surface to duplicate.
* \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
* more information.
+ *
+ * \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface *surface);
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 9c969f99e130..4d9ae3abd3e7 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -582,13 +582,41 @@ extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
/* Functions used by iOS application delegates to notify SDL about state changes */
+
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
+
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
+
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_OnApplicationWillResignActive(void);
+
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
+
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
+
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void);
+
#ifdef __IOS__
+/*
+ * \since This function is available since SDL 3.0.0.
+ */
extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
#endif
diff --git a/include/SDL3/SDL_test_font.h b/include/SDL3/SDL_test_font.h
index a5709326d44c..c3739b672a7c 100644
--- a/include/SDL3/SDL_test_font.h
+++ b/include/SDL3/SDL_test_font.h
@@ -88,7 +88,7 @@ typedef struct SDLTest_TextWindow
*
* \returns the new window, or NULL on failure.
*
- * \since This function is available since SDL 2.24.0
+ * \since This function is available since SDL 3.0.0.
*/
SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h);
@@ -100,7 +100,7 @@ SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h)
* \param textwin The text output window
* \param renderer The renderer to use for display
*
- * \since This function is available since SDL 2.24.0
+ * \since This function is available since SDL 3.0.0.
*/
void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer);
@@ -115,7 +115,7 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render
* \param fmt A printf() style format string
* \param ... additional parameters matching % tokens in the `fmt` string, if any
*
- * \since This function is available since SDL 2.24.0
+ * \since This function is available since SDL 3.0.0.
*/
void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
@@ -130,7 +130,7 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST
* \param text The text to add to the window
* \param len The length, in bytes, of the text to add to the window
*
- * \since This function is available since SDL 2.24.0
+ * \since This function is available since SDL 3.0.0.
*/
void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len);
@@ -139,7 +139,7 @@ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char
*
* \param textwin The text output window
*
- * \since This function is available since SDL 2.24.0
+ * \since This function is available since SDL 3.0.0.
*/
void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);
@@ -148,7 +148,7 @@ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);
*
* \param textwin The text output window
*
- * \since This function is available since SDL 2.24.0
+ * \since This function is available since SDL 3.0.0.
*/
void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin);
diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h
index 42552e7b458d..e4e23364a917 100644
--- a/include/SDL3/SDL_thread.h
+++ b/include/SDL3/SDL_thread.h
@@ -127,6 +127,8 @@ typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
* \param pfnSDL_CurrentEndThread end function
*
* \returns SDL_Thread pointer
+ *
+ * \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC SDL_Thread *SDLCALL
SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data,
@@ -144,6 +146,8 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data,
* \param pfnSDL_CurrentEndThread end function
*
* \returns SDL_Thread pointer
+ *
+ * \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC SDL_Thread *SDLCALL
SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn,
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index b746dd5ebc21..dee6474e7c8c 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -427,8 +427,6 @@ extern DECLSPEC const SDL_DisplayMode **SDLCALL SDL_GetFullscreenDisplayModes(SD
* \param h the height in pixels of the desired display mode
* \param refresh_rate the refresh rate of the desired display mode, or 0.0f for the desktop refresh rate
* \returns a pointer to the closest display mode equal to or larger than the desired mode, or NULL on error; call SDL_GetError() for more information.
- * \returns the passed in value `closest` or NULL if no matching video mode
- * was available; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*