include: More documentation updates.

include/SDL3/SDL_assert.h

@@ -36,7 +36,27 @@
 extern "C" {
 #endif
 
-#ifndef SDL_ASSERT_LEVEL
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
+/**
+ * The level of assertion aggressiveness.
+ *
+ * This value changes depending on compiler options and other
+ * preprocessor defines.
+ *
+ * It is currently one of the following values, but future SDL
+ * releases might add more:
+ *
+ * - 0: All SDL assertion macros are disabled.
+ * - 1: Release settings: SDL_assert disabled, SDL_assert_release enabled.
+ * - 2: Debug settings: SDL_assert and SDL_assert_release enabled.
+ * - 3: Paranoid settings: All SDL assertion macros enabled, including SDL_assert_paranoid.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_ASSERT_LEVEL SomeNumberBasedOnVariousFactors
+
+#elif !defined(SDL_ASSERT_LEVEL)
 #ifdef SDL_DEFAULT_ASSERT_LEVEL
 #define SDL_ASSERT_LEVEL SDL_DEFAULT_ASSERT_LEVEL
 #elif defined(_DEBUG) || defined(DEBUG) || \
@@ -45,7 +65,7 @@ extern "C" {
 #else
 #define SDL_ASSERT_LEVEL 1
 #endif
-#endif /* SDL_ASSERT_LEVEL */
+#endif
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
 
@@ -233,7 +253,6 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data
         } \
     } while (SDL_NULL_WHILE_LOOP_CONDITION)
 
-/* Enable various levels of assertions. */
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
 
 /**
@@ -333,6 +352,7 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data
 #define SDL_assert_paranoid(condition) SDL_disabled_assert(condition)
 #endif
 
+/* Enable various levels of assertions. */
 #if SDL_ASSERT_LEVEL == 0   /* assertions disabled */
 #   define SDL_assert(condition) SDL_disabled_assert(condition)
 #   define SDL_assert_release(condition) SDL_disabled_assert(condition)
@@ -385,6 +405,8 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data
  *             current assertion
  * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
  * \returns an SDL_AssertState value indicating how to handle the failure.
+ *
+ * \since This datatype is available since SDL 3.0.0.
  */
 typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
                                  const SDL_AssertData* data, void* userdata);

include/SDL3/SDL_mouse.h

@@ -144,7 +144,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
  * Retrieve the current state of the mouse.
  *
  * The current button state is returned as a button bitmask, which can be
- * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
+ * tested using the SDL_BUTTON(X) macro (where `X` is generally 1 for the
  * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
  * mouse cursor position relative to the focus window. You can pass NULL for
  * either `x` or `y`.
@@ -522,6 +522,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void);
  * \since This macro is available since SDL 3.0.0.
  */
 #define SDL_BUTTON(X)       (1 << ((X)-1))
+
 #define SDL_BUTTON_LEFT     1
 #define SDL_BUTTON_MIDDLE   2
 #define SDL_BUTTON_RIGHT    3

include/SDL3/SDL_pixels.h

@@ -496,8 +496,9 @@ typedef enum SDL_ColorPrimaries
 } SDL_ColorPrimaries;
 
 /**
- * The transfer characteristics, as described by
- * https://www.itu.int/rec/T-REC-H.273-201612-S/en
+ * The color transfer characteristics.
+ *
+ * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
  *
  * \since This enum is available since SDL 3.0.0.
  */
@@ -525,8 +526,9 @@ typedef enum SDL_TransferCharacteristics
 } SDL_TransferCharacteristics;
 
 /**
- * The matrix coefficients, as described by
- * https://www.itu.int/rec/T-REC-H.273-201612-S/en
+ * The matrix coefficients.
+ *
+ * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
  *
  * \since This enum is available since SDL 3.0.0.
  */
@@ -550,7 +552,7 @@ typedef enum SDL_MatrixCoefficients
 } SDL_MatrixCoefficients;
 
 /**
- * The chroma sample location
+ * The chroma sample location.
  *
  * \since This enum is available since SDL 3.0.0.
  */

include/SDL3/SDL_time.h

@@ -83,17 +83,27 @@ typedef enum SDL_TimeFormat
     SDL_TIME_FORMAT_12HR = 1  /**< 12 hour time */
 } SDL_TimeFormat;
 
-/*
- *  Global date/time properties.
+/* Global date/time properties. */
+
+/**
+ * The SDL_DateFormat to use as the preferred date display format for the current system locale.
  *
- *  - `SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER`: the SDL_DateFormat to use as the preferred date display format
- *    for the current system locale.
- *  - `SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER`: the SDL_TimeFormat to use as the preferred time display format
- *    for the current system locale.
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER
  */
 #define SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER "SDL.time.date_format"
+
+/**
+ * The SDL_TimeFormat to use as the preferred time display format for the current system locale.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER
+ */
 #define SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER "SDL.time.time_format"
 
+
 /**
  * Gets the current value of the system realtime clock in nanoseconds since
  * Jan 1, 1970 in Universal Coordinated Time (UTC).