Add \since docs where missing and resets some to 3.0.0

- remove a \returns

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,

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__))

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 */

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)
 {

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,

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);
 

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
 

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);
 

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,

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.
  *