include: Filled in more documentation gaps.

include/SDL3/SDL_endian.h

@@ -64,12 +64,70 @@ _m_prefetch(void *__P)
  *  \name The two types of endianness
  */
 /* @{ */
+
+
+/**
+ * A value to represent littleendian byteorder.
+ *
+ * This is used with the preprocessor macro SDL_BYTEORDER, to determine a
+ * platform's byte ordering:
+ *
+ * ```c
+ * #if SDL_BYTEORDER == SDL_LIL_ENDIAN
+ * SDL_Log("This system is littleendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_BYTEORDER
+ * \sa SDL_BIG_ENDIAN
+ */
 #define SDL_LIL_ENDIAN  1234
+
+/**
+ * A value to represent bigendian byteorder.
+ *
+ * This is used with the preprocessor macro SDL_BYTEORDER, to determine a
+ * platform's byte ordering:
+ *
+ * ```c
+ * #if SDL_BYTEORDER == SDL_BIG_ENDIAN
+ * SDL_Log("This system is bigendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_BYTEORDER
+ * \sa SDL_LIL_ENDIAN
+ */
 #define SDL_BIG_ENDIAN  4321
+
 /* @} */
 
 #ifndef SDL_BYTEORDER
-#ifdef SDL_PLATFORM_LINUX
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A macro that reports the target system's byte order.
+ *
+ * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other
+ * values in the future, if something else becomes popular). This can be
+ * tested with the preprocessor, so decisions can be made at compile time.
+ *
+ * ```c
+ * #if SDL_BYTEORDER == SDL_BIG_ENDIAN
+ * SDL_Log("This system is bigendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_LIL_ENDIAN
+ * \sa SDL_BIG_ENDIAN
+ */
+#define SDL_BYTEORDER   SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN
+#elif defined(SDL_PLATFORM_LINUX)
 #include <endian.h>
 #define SDL_BYTEORDER  __BYTE_ORDER
 #elif defined(SDL_PLATFORM_SOLARIS)
@@ -110,8 +168,28 @@ _m_prefetch(void *__P)
 #endif /* !SDL_BYTEORDER */
 
 #ifndef SDL_FLOATWORDORDER
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A macro that reports the target system's floating point word order.
+ *
+ * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other
+ * values in the future, if something else becomes popular). This can be
+ * tested with the preprocessor, so decisions can be made at compile time.
+ *
+ * ```c
+ * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN
+ * SDL_Log("This system's floats are bigendian.");
+ * #endif
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_LIL_ENDIAN
+ * \sa SDL_BIG_ENDIAN
+ */
+#define SDL_FLOATWORDORDER   SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN
 /* predefs from newer gcc versions: */
-#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__)
+#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__)
 #if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__)
 #define SDL_FLOATWORDORDER   SDL_LIL_ENDIAN
 #elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__)

include/SDL3/SDL_timer.h

@@ -38,16 +38,137 @@ extern "C" {
 #endif
 
 /* SDL time constants */
+
+/**
+ * Number of milliseconds in a second.
+ *
+ * This is always 1000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_MS_PER_SECOND   1000
+
+/**
+ * Number of microseconds in a second.
+ *
+ * This is always 1000000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_US_PER_SECOND   1000000
+
+/**
+ * Number of nanoseconds in a second.
+ *
+ * This is always 1000000000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_NS_PER_SECOND   1000000000LL
+
+/**
+ * Number of nanoseconds in a millisecond.
+ *
+ * This is always 1000000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_NS_PER_MS       1000000
+
+/**
+ * Number of nanoseconds in a microsecond.
+ *
+ * This is always 1000.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_NS_PER_US       1000
+
+/**
+ * Convert seconds to nanoseconds.
+ *
+ * This only converts whole numbers, not fractional seconds.
+ *
+ * \param S the number of seconds to convert.
+ * \return S, expressed in nanoseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_SECONDS_TO_NS(S)    (((Uint64)(S)) * SDL_NS_PER_SECOND)
+
+/**
+ * Convert nanoseconds to seconds.
+ *
+ * This performs a division, so the results can be dramatically different
+ * if `NS` is an integer or floating point value.
+ *
+ * \param NS the number of nanoseconds to convert.
+ * \return NS, expressed in seconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_NS_TO_SECONDS(NS)   ((NS) / SDL_NS_PER_SECOND)
+
+/**
+ * Convert milliseconds to nanoseconds.
+ *
+ * This only converts whole numbers, not fractional milliseconds.
+ *
+ * \param MS the number of milliseconds to convert.
+ * \return MS, expressed in nanoseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_MS_TO_NS(MS)        (((Uint64)(MS)) * SDL_NS_PER_MS)
+
+/**
+ * Convert nanoseconds to milliseconds.
+ *
+ * This performs a division, so the results can be dramatically different
+ * if `NS` is an integer or floating point value.
+ *
+ * \param NS the number of nanoseconds to convert.
+ * \return NS, expressed in milliseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_NS_TO_MS(NS)        ((NS) / SDL_NS_PER_MS)
+
+/**
+ * Convert microseconds to nanoseconds.
+ *
+ * This only converts whole numbers, not fractional microseconds.
+ *
+ * \param US the number of microseconds to convert.
+ * \return US, expressed in nanoseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_US_TO_NS(US)        (((Uint64)(US)) * SDL_NS_PER_US)
+
+/**
+ * Convert nanoseconds to microseconds.
+ *
+ * This performs a division, so the results can be dramatically different
+ * if `NS` is an integer or floating point value.
+ *
+ * \param NS the number of nanoseconds to convert.
+ * \return NS, expressed in microseconds.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_NS_TO_US(NS)        ((NS) / SDL_NS_PER_US)
 
 /**

include/SDL3/SDL_touch.h

@@ -38,21 +38,51 @@
 extern "C" {
 #endif
 
+/**
+ * A unique ID for a touch device.
+ *
+ * This ID is valid for the time the device is connected to the system, and is
+ * never reused for the lifetime of the application.
+ *
+ * The value 0 is an invalid ID.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef Uint64 SDL_TouchID;
+
+/**
+ * A unique ID for a single finger on a touch device.
+ *
+ * This ID is valid for the time the finger (stylus, etc) is touching, and is
+ * never reused for the lifetime of the application.
+ *
+ * The same physical finger will have a different ID if it lifts off the touch
+ * device and then starts a new touch, so this ID tracks the lifetime of a
+ * single continuous touch.
+ *
+ * The value 0 is an invalid ID.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef Uint64 SDL_FingerID;
 
+/**
+ * An enum that describes the type of a touch device.
+ *
+ * \since This enum is available since SDL 3.1.3.
+ */
 typedef enum SDL_TouchDeviceType
 {
     SDL_TOUCH_DEVICE_INVALID = -1,
-    SDL_TOUCH_DEVICE_DIRECT,            /* touch screen with window-relative coordinates */
-    SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */
-    SDL_TOUCH_DEVICE_INDIRECT_RELATIVE  /* trackpad with screen cursor-relative coordinates */
+    SDL_TOUCH_DEVICE_DIRECT,            /**< touch screen with window-relative coordinates */
+    SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */
+    SDL_TOUCH_DEVICE_INDIRECT_RELATIVE  /**< trackpad with screen cursor-relative coordinates */
 } SDL_TouchDeviceType;
 
 /**
  * Data about a single finger in a multitouch event.
  *
- * Each touch even is a collection of fingers that are simultaneously in
+ * Each touch event is a collection of fingers that are simultaneously in
  * contact with the touch device (so a "touch" can be a "multitouch," in
  * reality), and this struct reports details of the specific fingers.
  *
@@ -68,10 +98,18 @@ typedef struct SDL_Finger
     float pressure; /**< the quantity of pressure applied, normalized (0...1) */
 } SDL_Finger;
 
-/* Used as the device ID for mouse events simulated with touch input */
+/**
+ * The SDL_MouseID for mouse events simulated with touch input.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1)
 
-/* Used as the SDL_TouchID for touch events simulated with mouse input */
+/**
+ * The SDL_TouchID for touch events simulated with mouse input.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1)