diff --git a/include/SDL_version.h b/include/SDL_version.h
index d6a7a38ed..c42b93b89 100644
--- a/include/SDL_version.h
+++ b/include/SDL_version.h
@@ -92,6 +92,10 @@ typedef struct SDL_version
     \endverbatim
  *
  *  This assumes that there will never be more than 100 patchlevels.
+ *
+ *  In versions higher than 2.9.0, the minor version overflows into
+ *  the thousands digit: for example, 2.23.0 is encoded as 4300,
+ *  and 2.255.99 would be encoded as 25799.
  *  This macro will not be available in SDL 3.x.
  */
 #define SDL_VERSIONNUM(X, Y, Z)                     \
@@ -100,6 +104,8 @@ typedef struct SDL_version
 /**
  *  This is the version number macro for the current SDL version.
  *
+ *  In versions higher than 2.9.0, the minor version overflows into
+ *  the thousands digit: for example, 2.23.0 is encoded as 4300.
  *  This macro will not be available in SDL 3.x.
  *
  *  Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead.