include: add \brief to includes

.gitignore

@@ -148,3 +148,8 @@ test/testvulkan
 test/testwm
 test/testyuv
 test/torturethread
+
+# for Doxygen
+docs/output
+SDL.tag
+doxygen_warn.txt

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_
 

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

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_

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_

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_

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_

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.
+ */

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_

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__)

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_

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_

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_

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:

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.

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_

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_

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_

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_

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_

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

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

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:
  *

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

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_

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_

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>

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_

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.
  */
 
 /**

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>
 

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>
 

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_

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_

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_

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>

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_

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_

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

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_ */

include/SDL3/SDL_scancode.h

@@ -22,7 +22,7 @@
 /**
  *  \file SDL_scancode.h
  *
- *  Defines keyboard scancodes.
+ *  \brief Defines keyboard scancodes.
  */
 
 #ifndef SDL_scancode_h_

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_

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

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_

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_

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_

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_

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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.
  */

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>

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>

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_

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_

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_

include/SDL3/SDL_vulkan.h

@@ -22,7 +22,7 @@
 /**
  *  \file SDL_vulkan.h
  *
- *  Header file for functions to creating Vulkan surfaces on SDL windows.
+ *  \brief Header file for functions to creating Vulkan surfaces on SDL windows.
  */
 
 #ifndef SDL_vulkan_h_

include/build_config/SDL_build_config.h

@@ -26,6 +26,8 @@
 
 /**
  *  \file SDL_build_config.h
+ *
+ *  \brief This is a set of defines to configure the SDL features
  */
 
 /* Add any platform that doesn't build using the configure system. */

include/build_config/SDL_build_config.h.cmake

@@ -19,15 +19,15 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-#ifndef SDL_build_config_h_
-#define SDL_build_config_h_
-
 /**
- *  \file SDL_build_config.h.in
+ *  \file SDL_build_config.h
  *
- *  This is a set of defines to configure the SDL features
+ *  \brief This is a set of defines to configure the SDL features
  */
 
+#ifndef SDL_build_config_h_
+#define SDL_build_config_h_
+
 /* General platform specific identifiers */
 #include <SDL3/SDL_platform_defines.h>
 

include/build_config/SDL_build_config_emscripten.h

@@ -21,6 +21,7 @@
 
 #ifndef SDL_build_config_emscripten_h
 #define SDL_build_config_emscripten_h
+#define SDL_build_config_h_
 
 #include <SDL3/SDL_platform_defines.h>
 

include/build_config/SDL_revision.h.cmake

@@ -1,3 +1,33 @@
+/*
+  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_
+
 #cmakedefine SDL_VENDOR_INFO "@SDL_VENDOR_INFO@"
 
 #ifdef SDL_VENDOR_INFO
@@ -5,3 +35,5 @@
 #else
 #define SDL_REVISION "@SDL_REVISION@"
 #endif
+
+#endif /* SDL_revision_h_ */