From 0e0bb22f7902e41c99e4b02d3065fb1ece336e1c Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Thu, 2 May 2024 23:25:22 -0400 Subject: [PATCH] include: More documentation updates. --- include/SDL3/SDL_assert.h | 28 +++++++++++++++++++++++++--- include/SDL3/SDL_mouse.h | 3 ++- include/SDL3/SDL_pixels.h | 12 +++++++----- include/SDL3/SDL_time.h | 22 ++++++++++++++++------ 4 files changed, 50 insertions(+), 15 deletions(-) diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index 3c823c047..4f4f4a17f 100644 --- a/include/SDL3/SDL_assert.h +++ b/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); diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h index 11bf354bf..943203154 100644 --- a/include/SDL3/SDL_mouse.h +++ b/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 diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h index 495f447d4..1fbd9c52c 100644 --- a/include/SDL3/SDL_pixels.h +++ b/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. */ diff --git a/include/SDL3/SDL_time.h b/include/SDL3/SDL_time.h index c2d5ace32..6864ef4f2 100644 --- a/include/SDL3/SDL_time.h +++ b/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).