include: Improved SDL_GetTicks*() documentation a little.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
diff --git a/include/SDL_timer.h b/include/SDL_timer.h
index ed6be78..791f3b4 100644
--- a/include/SDL_timer.h
+++ b/include/SDL_timer.h
@@ -42,9 +42,11 @@ extern "C" {
*
* This value wraps if the program runs for more than ~49 days.
*
- * \deprecated This function is deprecated as of SDL 2.0.18; use
- * SDL_GetTicks64() instead, where the value doesn't wrap
- * every ~49 days.
+ * This function is not recommended as of SDL 2.0.18; use SDL_GetTicks64()
+ * instead, where the value doesn't wrap every ~49 days. There are places in
+ * SDL where we provide a 32-bit timestamp that can not change without
+ * breaking binary compatibility, though, so this function isn't officially
+ * deprecated.
*
* \returns an unsigned 32-bit value representing the number of milliseconds
* since the SDL library initialized.
@@ -53,15 +55,15 @@ extern "C" {
*
* \sa SDL_TICKS_PASSED
*/
-extern SDL_DEPRECATED DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
+extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
/**
* Get the number of milliseconds since SDL library initialization.
*
* Note that you should not use the SDL_TICKS_PASSED macro with values
* returned by this function, as that macro does clever math to compensate
- * for the 32-bit overflow every ~49 days. 64-bit values can just be safely
- * compared directly.
+ * for the 32-bit overflow every ~49 days that SDL_GetTicks() suffers from.
+ * 64-bit values from this function can be safely compared directly.
*
* For example, if you want to wait 100 ms, you could do this:
*
@@ -85,7 +87,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void);
* days, but should _not_ be used with SDL_GetTicks64(), which does not have
* that problem.
*
- * For example, if you want to wait 100 ms, you could do this:
+ * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could
+ * do this:
*
* ```c
* const Uint32 timeout = SDL_GetTicks() + 100;