From 549cedfa88cf93b69f8ffb4dd2c1ef097d3eb25c Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <[EMAIL REDACTED]>
Date: Sat, 18 Feb 2023 18:32:06 +0100
Subject: [PATCH] include: add \brief to includes
---
.gitignore | 5 +++
include/SDL3/SDL_assert.h | 6 ++++
include/SDL3/SDL_atomic.h | 4 +--
include/SDL3/SDL_audio.h | 2 +-
include/SDL3/SDL_bits.h | 2 +-
include/SDL3/SDL_blendmode.h | 2 +-
include/SDL3/SDL_clipboard.h | 2 +-
include/SDL3/SDL_copying.h | 6 ++++
include/SDL3/SDL_cpuinfo.h | 2 +-
include/SDL3/SDL_egl.h | 3 +-
include/SDL3/SDL_endian.h | 2 +-
include/SDL3/SDL_gamepad.h | 2 +-
include/SDL3/SDL_guid.h | 2 +-
include/SDL3/SDL_hidapi.h | 2 +-
include/SDL3/SDL_hints.h | 2 +-
include/SDL3/SDL_init.h | 2 +-
include/SDL3/SDL_intrin.h | 2 +-
include/SDL3/SDL_joystick.h | 16 +++++-----
include/SDL3/SDL_keyboard.h | 2 +-
include/SDL3/SDL_keycode.h | 2 +-
include/SDL3/SDL_loadso.h | 2 +-
include/SDL3/SDL_locale.h | 2 +-
include/SDL3/SDL_log.h | 2 +-
include/SDL3/SDL_main.h | 2 +-
include/SDL3/SDL_metal.h | 2 +-
include/SDL3/SDL_mouse.h | 2 +-
include/SDL3/SDL_mutex.h | 2 +-
include/SDL3/SDL_oldnames.h | 2 +-
include/SDL3/SDL_opengl.h | 2 +-
include/SDL3/SDL_opengles.h | 2 +-
include/SDL3/SDL_opengles2.h | 2 +-
include/SDL3/SDL_pixels.h | 2 +-
include/SDL3/SDL_platform.h | 2 +-
include/SDL3/SDL_platform_defines.h | 2 +-
include/SDL3/SDL_power.h | 2 +-
include/SDL3/SDL_quit.h | 2 +-
include/SDL3/SDL_rect.h | 2 +-
include/SDL3/SDL_render.h | 2 +-
include/SDL3/SDL_revision.h | 32 +++++++++++++++++++
include/SDL3/SDL_scancode.h | 2 +-
include/SDL3/SDL_sensor.h | 3 +-
include/SDL3/SDL_shape.h | 2 +-
include/SDL3/SDL_stdinc.h | 2 +-
include/SDL3/SDL_surface.h | 2 +-
include/SDL3/SDL_system.h | 2 +-
include/SDL3/SDL_syswm.h | 2 +-
include/SDL3/SDL_test.h | 2 +-
include/SDL3/SDL_test_assert.h | 2 +-
include/SDL3/SDL_test_common.h | 2 +-
include/SDL3/SDL_test_compare.h | 2 +-
include/SDL3/SDL_test_crc32.h | 2 +-
include/SDL3/SDL_test_font.h | 2 +-
include/SDL3/SDL_test_fuzzer.h | 2 +-
include/SDL3/SDL_test_harness.h | 2 +-
include/SDL3/SDL_test_log.h | 2 +-
include/SDL3/SDL_test_md5.h | 2 +-
include/SDL3/SDL_test_memory.h | 2 +-
include/SDL3/SDL_test_random.h | 2 +-
include/SDL3/SDL_thread.h | 2 +-
include/SDL3/SDL_timer.h | 2 +-
include/SDL3/SDL_touch.h | 2 +-
include/SDL3/SDL_version.h | 2 +-
include/SDL3/SDL_video.h | 2 +-
include/SDL3/SDL_vulkan.h | 2 +-
include/build_config/SDL_build_config.h | 2 ++
include/build_config/SDL_build_config.h.cmake | 10 +++---
.../SDL_build_config_emscripten.h | 1 +
include/build_config/SDL_revision.h.cmake | 32 +++++++++++++++++++
68 files changed, 158 insertions(+), 74 deletions(-)
diff --git a/.gitignore b/.gitignore
index 6a161a7be29a..e8f90c51b637 100644
--- a/.gitignore
+++ b/.gitignore
@@ -148,3 +148,8 @@ test/testvulkan
test/testwm
test/testyuv
test/torturethread
+
+# for Doxygen
+docs/output
+SDL.tag
+doxygen_warn.txt
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index 3846a37d228b..26b399b56996 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -19,6 +19,12 @@
3. This notice may not be removed or altered from any source distribution.
*/
+/**
+ * \file SDL_assert.h
+ *
+ * \brief Header file for assertion SDL API functions
+ */
+
#ifndef SDL_assert_h_
#define SDL_assert_h_
diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h
index 02069569db61..746bdc95786c 100644
--- a/include/SDL3/SDL_atomic.h
+++ b/include/SDL3/SDL_atomic.h
@@ -22,7 +22,7 @@
/**
* \file SDL_atomic.h
*
- * Atomic operations.
+ * \brief Atomic operations.
*
* IMPORTANT:
* If you are not an expert in concurrent lockless programming, you should
@@ -41,7 +41,7 @@
*
* You can find out a little more about lockless programming and the
* subtle issues that can arise here:
- * http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx
+ * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming
*
* There's also lots of good information here:
* http://www.1024cores.net/home/lock-free-algorithms
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 3f626255975d..e03680358e88 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -24,7 +24,7 @@
/**
* \file SDL_audio.h
*
- * Access to the raw audio mixing buffer for the SDL library.
+ * \brief Access to the raw audio mixing buffer for the SDL library.
*/
#ifndef SDL_audio_h_
diff --git a/include/SDL3/SDL_bits.h b/include/SDL3/SDL_bits.h
index 1d7c09c173aa..ffee5ad7cf87 100644
--- a/include/SDL3/SDL_bits.h
+++ b/include/SDL3/SDL_bits.h
@@ -22,7 +22,7 @@
/**
* \file SDL_bits.h
*
- * Functions for fiddling with bits and bitmasks.
+ * \brief Functions for fiddling with bits and bitmasks.
*/
#ifndef SDL_bits_h_
diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h
index 53771cea5613..50337cda7775 100644
--- a/include/SDL3/SDL_blendmode.h
+++ b/include/SDL3/SDL_blendmode.h
@@ -22,7 +22,7 @@
/**
* \file SDL_blendmode.h
*
- * Header file declaring the SDL_BlendMode enumeration
+ * \brief Header file declaring the SDL_BlendMode enumeration
*/
#ifndef SDL_blendmode_h_
diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h
index 9d8e3df6f62f..06b3ac84eced 100644
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@@ -22,7 +22,7 @@
/**
* \file SDL_clipboard.h
*
- * Include file for SDL clipboard handling
+ * \brief Include file for SDL clipboard handling
*/
#ifndef SDL_clipboard_h_
diff --git a/include/SDL3/SDL_copying.h b/include/SDL3/SDL_copying.h
index b6028bab2e3d..4b9c1dea9492 100644
--- a/include/SDL3/SDL_copying.h
+++ b/include/SDL3/SDL_copying.h
@@ -18,3 +18,9 @@
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
+
+/**
+ * \file SDL_copying.h
+ *
+ * \brief Header file containing SDL's license.
+ */
diff --git a/include/SDL3/SDL_cpuinfo.h b/include/SDL3/SDL_cpuinfo.h
index 9e7b807d76ec..09fe6342a6ff 100644
--- a/include/SDL3/SDL_cpuinfo.h
+++ b/include/SDL3/SDL_cpuinfo.h
@@ -22,7 +22,7 @@
/**
* \file SDL_cpuinfo.h
*
- * CPU feature detection for SDL.
+ * \brief CPU feature detection for SDL.
*/
#ifndef SDL_cpuinfo_h_
diff --git a/include/SDL3/SDL_egl.h b/include/SDL3/SDL_egl.h
index 077c6e202d44..d9c5d679102e 100644
--- a/include/SDL3/SDL_egl.h
+++ b/include/SDL3/SDL_egl.h
@@ -22,8 +22,9 @@
/**
* \file SDL_egl.h
*
- * This is a simple file to encapsulate the EGL API headers.
+ * \brief This is a simple file to encapsulate the EGL API headers.
*/
+
#if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)
#if defined(__vita__) || defined(__psp2__)
diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h
index a55a42f5ddbb..56f518f7887b 100644
--- a/include/SDL3/SDL_endian.h
+++ b/include/SDL3/SDL_endian.h
@@ -22,7 +22,7 @@
/**
* \file SDL_endian.h
*
- * Functions for reading and writing endian-specific values
+ * \brief Functions for reading and writing endian-specific values
*/
#ifndef SDL_endian_h_
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 814e4c4d1ed7..9ec44f52c279 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -22,7 +22,7 @@
/**
* \file SDL_gamepad.h
*
- * Include file for SDL gamepad event handling
+ * \brief Include file for SDL gamepad event handling
*/
#ifndef SDL_gamepad_h_
diff --git a/include/SDL3/SDL_guid.h b/include/SDL3/SDL_guid.h
index 11f1ffa6c27c..fbd70143fd07 100644
--- a/include/SDL3/SDL_guid.h
+++ b/include/SDL3/SDL_guid.h
@@ -22,7 +22,7 @@
/**
* \file SDL_guid.h
*
- * Include file for handling ::SDL_GUID values.
+ * \brief Include file for handling ::SDL_GUID values.
*/
#ifndef SDL_guid_h_
diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h
index 94b6f7a2dd97..987621b6abd7 100644
--- a/include/SDL3/SDL_hidapi.h
+++ b/include/SDL3/SDL_hidapi.h
@@ -22,7 +22,7 @@
/**
* \file SDL_hidapi.h
*
- * Header file for SDL HIDAPI functions.
+ * \brief Header file for SDL HIDAPI functions.
*
* This is an adaptation of the original HIDAPI interface by Alan Ott,
* and includes source code licensed under the following BSD license:
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index f041bcc64b55..552d59234d3d 100644
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
@@ -22,7 +22,7 @@
/**
* \file SDL_hints.h
*
- * Official documentation for SDL configuration variables
+ * \brief Official documentation for SDL configuration variables
*
* This file contains functions to set and get configuration hints,
* as well as listing each of them alphabetically.
diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h
index b10a14aa9681..361c653469fa 100644
--- a/include/SDL3/SDL_init.h
+++ b/include/SDL3/SDL_init.h
@@ -22,7 +22,7 @@
/**
* \file SDL_init.h
*
- * Init and quit header for the SDL library
+ * \brief Init and quit header for the SDL library
*/
#ifndef SDL_init_h_
diff --git a/include/SDL3/SDL_intrin.h b/include/SDL3/SDL_intrin.h
index 92db510dbcff..8add09baed0f 100644
--- a/include/SDL3/SDL_intrin.h
+++ b/include/SDL3/SDL_intrin.h
@@ -22,7 +22,7 @@
/**
* \file SDL_intrin.h
*
- * Header file for CPU intrinsics for SDL
+ * \brief Header file for CPU intrinsics for SDL
*/
#ifndef SDL_intrin_h_
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 44c7e7529b0a..005a072a0805 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -22,17 +22,17 @@
/**
* \file SDL_joystick.h
*
- * Include file for SDL joystick event handling
+ * \brief Include file for SDL joystick event handling
*
- * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
- * then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
+ * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
+ * then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
*
- * The term "player_index" is the number assigned to a player on a specific
- * controller. For XInput controllers this returns the XInput user index.
- * Many joysticks will not be able to supply this information.
+ * The term "player_index" is the number assigned to a player on a specific
+ * controller. For XInput controllers this returns the XInput user index.
+ * Many joysticks will not be able to supply this information.
*
- * The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
- * the device (a X360 wired controller for example). This identifier is platform dependent.
+ * The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
+ * the device (a X360 wired controller for example). This identifier is platform dependent.
*/
#ifndef SDL_joystick_h_
diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h
index 78661fcbcc2d..5b2df215a723 100644
--- a/include/SDL3/SDL_keyboard.h
+++ b/include/SDL3/SDL_keyboard.h
@@ -22,7 +22,7 @@
/**
* \file SDL_keyboard.h
*
- * Include file for SDL keyboard event handling
+ * \brief Include file for SDL keyboard event handling
*/
#ifndef SDL_keyboard_h_
diff --git a/include/SDL3/SDL_keycode.h b/include/SDL3/SDL_keycode.h
index 5107cc71a6f2..1e11a2e4da95 100644
--- a/include/SDL3/SDL_keycode.h
+++ b/include/SDL3/SDL_keycode.h
@@ -22,7 +22,7 @@
/**
* \file SDL_keycode.h
*
- * Defines constants which identify keyboard keys and modifiers.
+ * \brief Defines constants which identify keyboard keys and modifiers.
*/
#ifndef SDL_keycode_h_
diff --git a/include/SDL3/SDL_loadso.h b/include/SDL3/SDL_loadso.h
index 41439fd2d23d..f7ed6d2c3dda 100644
--- a/include/SDL3/SDL_loadso.h
+++ b/include/SDL3/SDL_loadso.h
@@ -22,7 +22,7 @@
/**
* \file SDL_loadso.h
*
- * System dependent library loading routines
+ * \brief System dependent library loading routines
*
* Some things to keep in mind:
* \li These functions only work on C function names. Other languages may
diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h
index f5896b2cffe7..d8c184203c19 100644
--- a/include/SDL3/SDL_locale.h
+++ b/include/SDL3/SDL_locale.h
@@ -22,7 +22,7 @@
/**
* \file SDL_locale.h
*
- * Include file for SDL locale services
+ * \brief Include file for SDL locale services
*/
#ifndef SDL_locale_h
diff --git a/include/SDL3/SDL_log.h b/include/SDL3/SDL_log.h
index 6428d55632cc..d56b05909f4d 100644
--- a/include/SDL3/SDL_log.h
+++ b/include/SDL3/SDL_log.h
@@ -22,7 +22,7 @@
/**
* \file SDL_log.h
*
- * Simple log messages with categories and priorities.
+ * \brief Simple log messages with categories and priorities.
*
* By default logs are quiet, but if you're debugging SDL you might want:
*
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index 573988379931..6954bd3334c5 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -27,7 +27,7 @@
/**
* \file SDL_main.h
*
- * Redefine main() on some platforms so that it is called by SDL.
+ * \brief Redefine main() on some platforms so that it is called by SDL.
*/
#ifndef SDL_MAIN_HANDLED
diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h
index 80a8c50efbe3..42ef3c86cb1f 100644
--- a/include/SDL3/SDL_metal.h
+++ b/include/SDL3/SDL_metal.h
@@ -22,7 +22,7 @@
/**
* \file SDL_metal.h
*
- * Header file for functions to creating Metal layers and views on SDL windows.
+ * \brief Header file for functions to creating Metal layers and views on SDL windows.
*/
#ifndef SDL_metal_h_
diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h
index 04df4e3f705f..d83715f9989f 100644
--- a/include/SDL3/SDL_mouse.h
+++ b/include/SDL3/SDL_mouse.h
@@ -22,7 +22,7 @@
/**
* \file SDL_mouse.h
*
- * Include file for SDL mouse event handling.
+ * \brief Include file for SDL mouse event handling.
*/
#ifndef SDL_mouse_h_
diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
index e4c9956447c8..83183dbc3ca1 100644
--- a/include/SDL3/SDL_mutex.h
+++ b/include/SDL3/SDL_mutex.h
@@ -25,7 +25,7 @@
/**
* \file SDL_mutex.h
*
- * Functions to provide thread synchronization primitives.
+ * \brief Functions to provide thread synchronization primitives.
*/
#include <SDL3/SDL_stdinc.h>
diff --git a/include/SDL3/SDL_oldnames.h b/include/SDL3/SDL_oldnames.h
index b54b2b1f6957..eeab931b9acc 100644
--- a/include/SDL3/SDL_oldnames.h
+++ b/include/SDL3/SDL_oldnames.h
@@ -22,7 +22,7 @@
/**
* \file SDL_oldnames.h
*
- * Definitions to ease transition from SDL2 code
+ * \brief Definitions to ease transition from SDL2 code
*/
#ifndef SDL_oldnames_h_
diff --git a/include/SDL3/SDL_opengl.h b/include/SDL3/SDL_opengl.h
index 5cfec4e1fcca..75c665a6403d 100644
--- a/include/SDL3/SDL_opengl.h
+++ b/include/SDL3/SDL_opengl.h
@@ -22,7 +22,7 @@
/**
* \file SDL_opengl.h
*
- * This is a simple file to encapsulate the OpenGL API headers.
+ * \brief This is a simple file to encapsulate the OpenGL API headers.
*/
/**
diff --git a/include/SDL3/SDL_opengles.h b/include/SDL3/SDL_opengles.h
index 5f50b5385305..11f57868fed4 100644
--- a/include/SDL3/SDL_opengles.h
+++ b/include/SDL3/SDL_opengles.h
@@ -22,7 +22,7 @@
/**
* \file SDL_opengles.h
*
- * This is a simple file to encapsulate the OpenGL ES 1.X API headers.
+ * \brief This is a simple file to encapsulate the OpenGL ES 1.X API headers.
*/
#include <SDL3/SDL_platform_defines.h>
diff --git a/include/SDL3/SDL_opengles2.h b/include/SDL3/SDL_opengles2.h
index abbe47b76e2f..eee6162fd0ce 100644
--- a/include/SDL3/SDL_opengles2.h
+++ b/include/SDL3/SDL_opengles2.h
@@ -22,7 +22,7 @@
/**
* \file SDL_opengles2.h
*
- * This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
+ * \brief This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
*/
#include <SDL3/SDL_platform_defines.h>
diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h
index ca980beab88a..fe6eadd0791f 100644
--- a/include/SDL3/SDL_pixels.h
+++ b/include/SDL3/SDL_pixels.h
@@ -22,7 +22,7 @@
/**
* \file SDL_pixels.h
*
- * Header for the enumerated pixel format definitions.
+ * \brief Header for the enumerated pixel format definitions.
*/
#ifndef SDL_pixels_h_
diff --git a/include/SDL3/SDL_platform.h b/include/SDL3/SDL_platform.h
index b2171fbbfb1a..c97761562092 100644
--- a/include/SDL3/SDL_platform.h
+++ b/include/SDL3/SDL_platform.h
@@ -22,7 +22,7 @@
/**
* \file SDL_platform.h
*
- * Header file for platform functions.
+ * \brief Header file for platform functions.
*/
#ifndef SDL_platform_h_
diff --git a/include/SDL3/SDL_platform_defines.h b/include/SDL3/SDL_platform_defines.h
index 88412369ebb3..0122f69e4386 100644
--- a/include/SDL3/SDL_platform_defines.h
+++ b/include/SDL3/SDL_platform_defines.h
@@ -22,7 +22,7 @@
/**
* \file SDL_platform_defines.h
*
- * Try to get a standard set of platform defines.
+ * \brief Try to get a standard set of platform defines.
*/
#ifndef SDL_platform_defines_h_
diff --git a/include/SDL3/SDL_power.h b/include/SDL3/SDL_power.h
index 5bb381b90a95..db83ccf197bd 100644
--- a/include/SDL3/SDL_power.h
+++ b/include/SDL3/SDL_power.h
@@ -25,7 +25,7 @@
/**
* \file SDL_power.h
*
- * Header for the SDL power management routines.
+ * \brief Header for the SDL power management routines.
*/
#include <SDL3/SDL_stdinc.h>
diff --git a/include/SDL3/SDL_quit.h b/include/SDL3/SDL_quit.h
index 18ef4142ed24..4087e601c0d6 100644
--- a/include/SDL3/SDL_quit.h
+++ b/include/SDL3/SDL_quit.h
@@ -22,7 +22,7 @@
/**
* \file SDL_quit.h
*
- * Include file for SDL quit event handling.
+ * \brief Include file for SDL quit event handling.
*/
#ifndef SDL_quit_h_
diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h
index 1b5ce0410fc9..c50f168fe3e1 100644
--- a/include/SDL3/SDL_rect.h
+++ b/include/SDL3/SDL_rect.h
@@ -22,7 +22,7 @@
/**
* \file SDL_rect.h
*
- * Header file for SDL_rect definition and management functions.
+ * \brief Header file for SDL_rect definition and management functions.
*/
#ifndef SDL_rect_h_
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 45cec60daab6..1eea867d1319 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -22,7 +22,7 @@
/**
* \file SDL_render.h
*
- * Header file for SDL 2D rendering functions.
+ * \brief Header file for SDL 2D rendering functions.
*
* This API supports the following features:
* * single pixel points
diff --git a/include/SDL3/SDL_revision.h b/include/SDL3/SDL_revision.h
index 4f225a48c802..d77f3a1ec06d 100644
--- a/include/SDL3/SDL_revision.h
+++ b/include/SDL3/SDL_revision.h
@@ -1,5 +1,37 @@
+/*
+ Simple DirectMedia Layer
+ Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely, subject to the following restrictions:
+
+ 1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+ 2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+ 3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ * \file SDL_revision.h
+ *
+ * \brief Header file containing the SDL revision
+ */
+
+#ifndef SDL_revision_h_
+#define SDL_revision_h_
+
#ifdef SDL_VENDOR_INFO
#define SDL_REVISION SDL_VENDOR_INFO
#else
#define SDL_REVISION ""
#endif
+
+#endif /* SDL_revision_h_ */
\ No newline at end of file
diff --git a/include/SDL3/SDL_scancode.h b/include/SDL3/SDL_scancode.h
index f90076c187c7..30b0a751cf37 100644
--- a/include/SDL3/SDL_scancode.h
+++ b/include/SDL3/SDL_scancode.h
@@ -22,7 +22,7 @@
/**
* \file SDL_scancode.h
*
- * Defines keyboard scancodes.
+ * \brief Defines keyboard scancodes.
*/
#ifndef SDL_scancode_h_
diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h
index ad0d980d3ca6..5211f01009f8 100644
--- a/include/SDL3/SDL_sensor.h
+++ b/include/SDL3/SDL_sensor.h
@@ -22,8 +22,7 @@
/**
* \file SDL_sensor.h
*
- * Include file for SDL sensor event handling
- *
+ * \brief Include file for SDL sensor event handling
*/
#ifndef SDL_sensor_h_
diff --git a/include/SDL3/SDL_shape.h b/include/SDL3/SDL_shape.h
index 9c5c2cf5df19..36fa1ed71d6c 100644
--- a/include/SDL3/SDL_shape.h
+++ b/include/SDL3/SDL_shape.h
@@ -36,7 +36,7 @@ extern "C" {
/** \file SDL_shape.h
*
- * Header file for the shaped window API.
+ * \brief Header file for the shaped window API.
*/
#define SDL_NONSHAPEABLE_WINDOW -1
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 1412800a9da7..da59fe533445 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -22,7 +22,7 @@
/**
* \file SDL_stdinc.h
*
- * This is a general header that includes C language support.
+ * \brief This is a general header that includes C language support.
*/
#ifndef SDL_stdinc_h_
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 5d3836456fce..100d297eb26b 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -22,7 +22,7 @@
/**
* \file SDL_surface.h
*
- * Header file for ::SDL_Surface definition and management functions.
+ * \brief Header file for ::SDL_Surface definition and management functions.
*/
#ifndef SDL_surface_h_
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 4d9ae3abd3e7..7d6860fe688f 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -22,7 +22,7 @@
/**
* \file SDL_system.h
*
- * Include file for platform specific SDL API functions
+ * \brief Include file for platform specific SDL API functions
*/
#ifndef SDL_system_h_
diff --git a/include/SDL3/SDL_syswm.h b/include/SDL3/SDL_syswm.h
index 839491082eb5..8c85bf37afec 100644
--- a/include/SDL3/SDL_syswm.h
+++ b/include/SDL3/SDL_syswm.h
@@ -22,7 +22,7 @@
/**
* \file SDL_syswm.h
*
- * Include file for SDL custom system window manager hooks.
+ * \brief Include file for SDL custom system window manager hooks.
*/
#ifndef SDL_syswm_h_
diff --git a/include/SDL3/SDL_test.h b/include/SDL3/SDL_test.h
index 3e51601dd7f7..d66d26b0b398 100644
--- a/include/SDL3/SDL_test.h
+++ b/include/SDL3/SDL_test.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test.h
*
- * Include file for SDL test framework.
+ * \brief Include file for SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_assert.h b/include/SDL3/SDL_test_assert.h
index 838b1d497044..b140c9d91ff8 100644
--- a/include/SDL3/SDL_test_assert.h
+++ b/include/SDL3/SDL_test_assert.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_assert.h
*
- * Include file for SDL test framework.
+ * \brief Assertion functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_common.h b/include/SDL3/SDL_test_common.h
index b7b2df90bd66..9e44e7b1275f 100644
--- a/include/SDL3/SDL_test_common.h
+++ b/include/SDL3/SDL_test_common.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_common.h
*
- * Include file for SDL test framework.
+ * \brief Common functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_compare.h b/include/SDL3/SDL_test_compare.h
index 734a2eac5bfb..6de16a623df7 100644
--- a/include/SDL3/SDL_test_compare.h
+++ b/include/SDL3/SDL_test_compare.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_compare.h
*
- * Include file for SDL test framework.
+ * \brief Comparison function of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_crc32.h b/include/SDL3/SDL_test_crc32.h
index 59cae4e8cf9f..8d7f2651fa95 100644
--- a/include/SDL3/SDL_test_crc32.h
+++ b/include/SDL3/SDL_test_crc32.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_crc32.h
*
- * Include file for SDL test framework.
+ * \brief CRC32 functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_font.h b/include/SDL3/SDL_test_font.h
index c3739b672a7c..c5146fcad4e3 100644
--- a/include/SDL3/SDL_test_font.h
+++ b/include/SDL3/SDL_test_font.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_font.h
*
- * Include file for SDL test framework.
+ * \brief Font related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_fuzzer.h b/include/SDL3/SDL_test_fuzzer.h
index be3f6580e72a..2cfdbf53fdd3 100644
--- a/include/SDL3/SDL_test_fuzzer.h
+++ b/include/SDL3/SDL_test_fuzzer.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_fuzzer.h
*
- * Include file for SDL test framework.
+ * \brief Fuzzer functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_harness.h b/include/SDL3/SDL_test_harness.h
index f50d43906ed9..c8a7d120b7b2 100644
--- a/include/SDL3/SDL_test_harness.h
+++ b/include/SDL3/SDL_test_harness.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_harness.h
*
- * Include file for SDL test framework.
+ * \brief Test suite related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_log.h b/include/SDL3/SDL_test_log.h
index b62711870627..fa4be923a368 100644
--- a/include/SDL3/SDL_test_log.h
+++ b/include/SDL3/SDL_test_log.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_log.h
*
- * Include file for SDL test framework.
+ * \brief Logging related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_md5.h b/include/SDL3/SDL_test_md5.h
index a618390e5329..bf680c150bff 100644
--- a/include/SDL3/SDL_test_md5.h
+++ b/include/SDL3/SDL_test_md5.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_md5.h
*
- * Include file for SDL test framework.
+ * \brief MD5 related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_memory.h b/include/SDL3/SDL_test_memory.h
index da71a0d93db3..1b3f7d39b9e6 100644
--- a/include/SDL3/SDL_test_memory.h
+++ b/include/SDL3/SDL_test_memory.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_memory.h
*
- * Include file for SDL test framework.
+ * \brief Memory tracking related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_test_random.h b/include/SDL3/SDL_test_random.h
index fe94d09b3195..50bc116b33c7 100644
--- a/include/SDL3/SDL_test_random.h
+++ b/include/SDL3/SDL_test_random.h
@@ -22,7 +22,7 @@
/**
* \file SDL_test_random.h
*
- * Include file for SDL test framework.
+ * \brief Random number generator related function of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h
index e4e23364a917..05b9599860a2 100644
--- a/include/SDL3/SDL_thread.h
+++ b/include/SDL3/SDL_thread.h
@@ -25,7 +25,7 @@
/**
* \file SDL_thread.h
*
- * Header for the SDL thread management routines.
+ * \brief Header for the SDL thread management routines.
*/
#include <SDL3/SDL_stdinc.h>
diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h
index 99c4795c8172..e8049df8a472 100644
--- a/include/SDL3/SDL_timer.h
+++ b/include/SDL3/SDL_timer.h
@@ -25,7 +25,7 @@
/**
* \file SDL_timer.h
*
- * Header for the SDL time management routines.
+ * \brief Header for the SDL time management routines.
*/
#include <SDL3/SDL_stdinc.h>
diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h
index df24da43dce0..cc1a9de1c19d 100644
--- a/include/SDL3/SDL_touch.h
+++ b/include/SDL3/SDL_touch.h
@@ -22,7 +22,7 @@
/**
* \file SDL_touch.h
*
- * Include file for SDL touch event handling.
+ * \brief Include file for SDL touch event handling.
*/
#ifndef SDL_touch_h_
diff --git a/include/SDL3/SDL_version.h b/include/SDL3/SDL_version.h
index 4f34f9487c26..0c7a59899b07 100644
--- a/include/SDL3/SDL_version.h
+++ b/include/SDL3/SDL_version.h
@@ -22,7 +22,7 @@
/**
* \file SDL_version.h
*
- * This header defines the current SDL version.
+ * \brief This header defines the current SDL version.
*/
#ifndef SDL_version_h_
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index dee6474e7c8c..749f2e999643 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -22,7 +22,7 @@
/**
* \file SDL_video.h
*
- * Header file for SDL video functions.
+ * \brief Header file for SDL video functions.
*/
#ifndef SDL_video_h_
diff --git a/include/SDL3/SDL_vulkan.h b/include/SDL3/SDL_vulkan.h
index 24f79b32e013..13047c9d0c82 100644
--- a/include/SDL3/SDL_vulkan.h
+++ b/include/SDL3/SDL_vulkan.h
@@ -22,7 +22,7 @@
/**
* \file SDL_vulkan.h
*
- * Header file for functions to creating Vulka
(Patch may be truncated, please check the link at the top of this post.)