Add \since docs where missing and resets some to 3.0.0

- remove a \returns
2023-02-12 20:39:22 +01:00 · 2023-02-12 20:39:22 +01:00 · 81c94a165c
parent 3d93b07d5b
commit 81c94a165c
10 changed files with 54 additions and 12 deletions
--- 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,
--- 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__))
--- 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 */
--- 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)
 {
--- 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,
--- 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);

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

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

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