From 79316ca36ed460b37b3b1eb316b235b98a480705 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 16 Dec 2024 01:10:37 -0500
Subject: [PATCH] Heavy work on improving category documentation.
Still more to go!
Reference Issue #9440.
---
include/SDL3/SDL.h | 7 +++--
include/SDL3/SDL_assert.h | 11 +++++--
include/SDL3/SDL_begin_code.h | 3 ++
include/SDL3/SDL_bits.h | 4 ---
include/SDL3/SDL_blendmode.h | 2 +-
include/SDL3/SDL_camera.h | 27 ++++++++++++++---
include/SDL3/SDL_clipboard.h | 52 +++++++++++++++++++++++++++++++--
include/SDL3/SDL_close_code.h | 5 +++-
include/SDL3/SDL_cpuinfo.h | 5 ++++
include/SDL3/SDL_dialog.h | 6 ++--
include/SDL3/SDL_endian.h | 18 ++++++++----
include/SDL3/SDL_error.h | 35 ++++++++++++++++++++++
include/SDL3/SDL_events.h | 24 +++++++++++++++
include/SDL3/SDL_guid.h | 2 ++
include/SDL3/SDL_intrin.h | 2 +-
include/SDL3/SDL_joystick.h | 2 +-
include/SDL3/SDL_keyboard.h | 5 ++++
include/SDL3/SDL_keycode.h | 5 ++++
include/SDL3/SDL_loadso.h | 5 ++++
include/SDL3/SDL_locale.h | 6 ++++
include/SDL3/SDL_main.h | 7 +++++
include/SDL3/SDL_scancode.h | 5 ++++
include/SDL3/SDL_test.h | 2 --
include/SDL3/SDL_test_common.h | 2 --
include/SDL3/SDL_test_compare.h | 2 --
include/SDL3/SDL_test_font.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 --
30 files changed, 210 insertions(+), 44 deletions(-)
diff --git a/include/SDL3/SDL.h b/include/SDL3/SDL.h
index e309929a122c1..e36c67b6db163 100644
--- a/include/SDL3/SDL.h
+++ b/include/SDL3/SDL.h
@@ -20,9 +20,12 @@
*/
/**
- * \file SDL.h
+ * Main include header for the SDL library, version 3.1.7
*
- * Main include header for the SDL library, version 3.1.7
+ * It is almost always best to include just this one header instead of
+ * picking out individual headers included here. There are exceptions to
+ * this rule--SDL_main.h is special and not included here--but usually
+ * letting SDL.h include the kitchen sink for you is the correct approach.
*/
#ifndef SDL_h_
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index d09e46c0f142b..6f6cd19e9071c 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -51,9 +51,14 @@
* - It provides statistics and data on all failed assertions to the app.
* - It allows the default assertion handler to be controlled with environment
* variables, in case an automated script needs to control it.
- *
- * To use it: do a debug build and just sprinkle around tests to check your
- * code!
+ * - It can be used as an aid to Clang's static analysis; it will treat SDL
+ * assertions as universally true (under the assumption that you are serious
+ * about the asserted claims and that your debug builds will detect when
+ * these claims were wrong). This can help the analyzer avoid false
+ * positives.
+ *
+ * To use it: compile a debug build and just sprinkle around tests to check
+ * your code!
*/
#ifndef SDL_assert_h_
diff --git a/include/SDL3/SDL_begin_code.h b/include/SDL3/SDL_begin_code.h
index acf99284c20da..6c9116278e78a 100644
--- a/include/SDL3/SDL_begin_code.h
+++ b/include/SDL3/SDL_begin_code.h
@@ -25,6 +25,9 @@
* SDL_begin_code.h sets things up for C dynamic library function definitions,
* static inlined functions, and structures aligned at 4-byte alignment.
* If you don't like ugly C preprocessor code, don't look at this file. :)
+ *
+ * SDL's headers use this; applications generally should not include this
+ * header directly.
*/
/* This shouldn't be nested -- included it around code only. */
diff --git a/include/SDL3/SDL_bits.h b/include/SDL3/SDL_bits.h
index cabf92d17c3e2..71f356ce67bb1 100644
--- a/include/SDL3/SDL_bits.h
+++ b/include/SDL3/SDL_bits.h
@@ -36,10 +36,6 @@
extern "C" {
#endif
-/**
- * \file SDL_bits.h
- */
-
#if defined(__WATCOMC__) && defined(__386__)
extern __inline int _SDL_bsr_watcom(Uint32);
#pragma aux _SDL_bsr_watcom = \
diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h
index 0998c1a1eef05..b9dbbe4b30db4 100644
--- a/include/SDL3/SDL_blendmode.h
+++ b/include/SDL3/SDL_blendmode.h
@@ -24,7 +24,7 @@
*
* Blend modes decide how two colors will mix together. There are both
* standard modes for basic needs and a means to create custom modes,
- * dictating what sort of math to do what on what color components.
+ * dictating what sort of math to do on what color components.
*/
#ifndef SDL_blendmode_h_
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index 5ac47ea6d2bb7..849684aaf8572 100644
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -29,6 +29,25 @@
* provide SDL_Surface objects as new frames of video come in. These surfaces
* can be uploaded to an SDL_Texture or processed as pixels in memory.
*
+ * Several platforms will alert the user if an app tries to access a camera,
+ * and some will present a UI asking the user if your application should be
+ * allowed to obtain images at all, which they can deny. A successfully
+ * opened camera will not provide images until permission is granted.
+ * Applications, after opening a camera device, can see if they were granted
+ * access by either polling with the SDL_GetCameraPermissionState() function,
+ * or waiting for an SDL_EVENT_CAMERA_DEVICE_APPROVED or
+ * SDL_EVENT_CAMERA_DEVICE_DENIED event. Platforms that don't have any
+ * user approval process will report approval immediately.
+ *
+ * Note that SDL cameras only provide video as individual frames; they will
+ * not provide full-motion video encoded in a movie file format, although an
+ * app is free to encode the acquired frames into any format it likes. It
+ * also does not provide audio from the camera hardware through this API;
+ * not only do many webcams not have microphones at all, many people--from
+ * streamers to people on Zoom calls--will want to use a separate microphone
+ * regardless of the camera. In any case, recorded audio will be available
+ * through SDL's audio API no matter what hardware provides the microphone.
+ *
* ## Camera gotchas
*
* Consumer-level camera hardware tends to take a little while to warm up,
@@ -40,10 +59,10 @@
*
* It's not uncommon that a newly-opened camera will provide a couple of
* completely black frames, maybe followed by some under-exposed images. If
- * taking single frame automatically, or recording video from a camera's input
- * without the user initiating it from a preview, it could be wise to drop the
- * first several frames (if not the first several _seconds_ worth of frames!)
- * before using images from a camera.
+ * taking a single frame automatically, or recording video from a camera's
+ * input without the user initiating it from a preview, it could be wise to
+ * drop the first several frames (if not the first several _seconds_ worth of
+ * frames!) before using images from a camera.
*/
#ifndef SDL_camera_h_
diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h
index 21206f288f38e..f6be9d8d5ebfc 100644
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@@ -26,6 +26,52 @@
* from other processes and publishing information of its own.
*
* This is not just text! SDL apps can access and publish data by mimetype.
+ *
+ * ## Basic use (text)
+ *
+ * Obtaining and publishing simple text to the system clipboard is as easy
+ * as calling SDL_GetClipboardText() and SDL_SetClipboardText(),
+ * respectively. These deal with C strings in UTF-8 encoding. Data
+ * transmission and encoding conversion is completely managed by SDL.
+ *
+ * ## Clipboard callbacks (data other than text)
+ *
+ * Things get more complicated when the clipboard contains something other
+ * than text. Not only can the system clipboard contain data of any type,
+ * in some cases it can contain the same data in different formats! For
+ * example, an image painting app might let the user copy a graphic to the
+ * clipboard, and offers it in .BMP, .JPG, or .PNG format for other apps to
+ * consume.
+ *
+ * Obtaining clipboard data ("pasting") like this is a matter of calling
+ * SDL_GetClipboardData() and telling it the mimetype of the data you want.
+ * But how does one know if that format is available? SDL_HasClipboardData()
+ * can report if a specific mimetype is offered, and
+ * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes
+ * available, so the app can decide what to do with the data and what formats
+ * it can support.
+ *
+ * Setting the clipboard ("copying") to arbitrary data is done with
+ * SDL_SetClipboardData. The app does not provide the data in this call, but
+ * rather the mimetypes it is willing to provide and a callback function.
+ * During the callback, the app will generate the data. This allows massive
+ * data sets to be provided to the clipboard, without any data being copied
+ * before it is explicitly requested. More specifically, it allows an app
+ * to offer data in multiple formats without providing a copy of all of
+ * them upfront. If the app has an image that it could provide in PNG or JPG
+ * format, it doesn't have to encode it to either of those unless and until
+ * something tries to paste it.
+ *
+ * ## Primary Selection
+ *
+ * The X11 and Wayland video targets have a concept of the "primary selection"
+ * in addition to the usual clipboard. This is generally highlighted (but not
+ * explicitly copied) text from various apps. SDL offers APIs for this through
+ * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText().
+ * SDL offers these APIs on platforms without this concept, too, but only so
+ * far that it will keep a copy of a string that the app sets for later
+ * retrieval; the operating system will not ever attempt to change the
+ * string externally if it doesn't support a primary selection.
*/
#ifndef SDL_clipboard_h_
@@ -181,13 +227,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
* Offer clipboard data to the OS.
*
* Tell the operating system that the application is offering clipboard data
- * for each of the proivded mime-types. Once another application requests the
- * data the callback function will be called allowing it to generate and
+ * for each of the provided mime-types. Once another application requests the
+ * data the callback function will be called, allowing it to generate and
* respond with the data for the requested mime-type.
*
* The size of text data does not include any terminator, and the text does
* not need to be null terminated (e.g. you can directly copy a portion of a
- * document)
+ * document).
*
* \param callback a function pointer to the function that provides the
* clipboard data.
diff --git a/include/SDL3/SDL_close_code.h b/include/SDL3/SDL_close_code.h
index fa4d3d17bae3f..aba9066cb7a0f 100644
--- a/include/SDL3/SDL_close_code.h
+++ b/include/SDL3/SDL_close_code.h
@@ -21,7 +21,10 @@
/*
* This file reverses the effects of SDL_begin_code.h and should be included
- * after you finish any function and structure declarations in your headers
+ * after you finish any function and structure declarations in your headers.
+ *
+ * SDL's headers use this; applications generally should not include this
+ * header directly.
*/
#ifndef SDL_begin_code_h
diff --git a/include/SDL3/SDL_cpuinfo.h b/include/SDL3/SDL_cpuinfo.h
index 8d47d92d3336d..94e366c23c78a 100644
--- a/include/SDL3/SDL_cpuinfo.h
+++ b/include/SDL3/SDL_cpuinfo.h
@@ -29,6 +29,11 @@
* These functions are largely concerned with reporting if the system has
* access to various SIMD instruction sets, but also has other important info
* to share, such as system RAM size and number of logical CPU cores.
+ *
+ * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are
+ * available on all platforms, even if they don't make sense (an ARM processor
+ * will never have SSE and an x86 processor will never have NEON, for example,
+ * but these functions still exist and will simply return false in these cases).
*/
#ifndef SDL_cpuinfo_h_
diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h
index e5b534a2222fe..9d66573f66454 100644
--- a/include/SDL3/SDL_dialog.h
+++ b/include/SDL3/SDL_dialog.h
@@ -276,9 +276,9 @@ typedef enum SDL_FileDialogType
* These are the supported properties:
*
* - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of
- * SDL_DialogFileFilter's, which will be used as filters for file-based
- * selections. Ignored if the dialog is an "Open Folder" dialog. If
- * non-NULL, the array of filters must remain valid at least until the
+ * SDL_DialogFileFilter structs, which will be used as filters for
+ * file-based selections. Ignored if the dialog is an "Open Folder" dialog.
+ * If non-NULL, the array of filters must remain valid at least until the
* callback is invoked.
* - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the
* array of filters, if it exists.
diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h
index 50a8db8865cab..d1c1173284612 100644
--- a/include/SDL3/SDL_endian.h
+++ b/include/SDL3/SDL_endian.h
@@ -22,7 +22,19 @@
/**
* # CategoryEndian
*
- * Functions for reading and writing endian-specific values.
+ * Functions converting endian-specific values to different byte orders.
+ *
+ * These functions either unconditionally swap byte order (SDL_Swap16,
+ * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's
+ * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE,
+ * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the
+ * latter case, the functionality is provided by macros that become no-ops
+ * if a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE
+ * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC
+ * processor (bigendian), the macros behavior is reversed.
+ *
+ * The swap routines are inline functions, and attempt to use compiler
+ * intrinsics, inline assembly, and other magic to make byteswapping efficient.
*/
#ifndef SDL_endian_h_
@@ -125,10 +137,6 @@ _m_prefetch(void *__P)
extern "C" {
#endif
-/**
- * \file SDL_endian.h
- */
-
/* various modern compilers may have builtin swap */
#if defined(__GNUC__) || defined(__clang__)
# define HAS_BUILTIN_BSWAP16 (SDL_HAS_BUILTIN(__builtin_bswap16)) || \
diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h
index 6818e411a3f90..c96d1511a302a 100644
--- a/include/SDL3/SDL_error.h
+++ b/include/SDL3/SDL_error.h
@@ -178,8 +178,43 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void);
* Private error reporting function - used internally.
*/
/* @{ */
+
+/**
+ * A macro to standardize error reporting on unsupported operations.
+ *
+ * This simply calls SDL_SetError() with a standardized error string, for
+ * convenience, consistency, and clarity.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_Unsupported() SDL_SetError("That operation is not supported")
+
+/**
+ * A macro to standardize error reporting on unsupported operations.
+ *
+ * This simply calls SDL_SetError() with a standardized error string, for
+ * convenience, consistency, and clarity.
+ *
+ * A common usage pattern inside SDL is this:
+ *
+ * ```c
+ * bool MyFunction(const char *str) {
+ * if (!str) {
+ * return SDL_InvalidParamError("str"); // returns false.
+ * }
+ * DoSomething(str);
+ * return true;
+ * }
+ * ```
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
#define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param))
+
/* @} *//* Internal error functions */
/* Ends C function definitions when using C++ */
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index d21567a47a0ec..596bdd124b681 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -23,6 +23,30 @@
* # CategoryEvents
*
* Event queue management.
+ *
+ * It's extremely common--often required--that an app deal with SDL's event
+ * queue. Almost all useful information about interactions with the real
+ * world flow through here: the user interacting with the computer and app,
+ * hardware coming and going, the system changing in some way, etc.
+ *
+ * An app generally takes a moment, perhaps at the start of a new frame, to
+ * examine any events that have occured since the last time and process or
+ * ignore them. This is generally done by calling SDL_PollEvent() in a loop
+ * until it returns false (or, if using the main callbacks, events are
+ * provided one at a time in calls to SDL_AppEvent() before the next call to
+ * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent()
+ * at all).
+ *
+ * There is other forms of control, too: SDL_PeepEvents() has more
+ * functionality at the cost of more complexity, and SDL_WaitEvents() can
+ * block the process until something interesting happens, which might be
+ * beneficial for certain types of programs on low-power hardware. One may
+ * also call SDL_AddEventWatch() to set a callback when new events arrive.
+ *
+ * The app is free to generate their own events, too: SDL_PushEvent allows
+ * the app to put events onto the queue for later retrieval;
+ * SDL_RegisterEvents can guarantee that these events have a type that isn't
+ * in use by other parts of the system.
*/
#ifndef SDL_events_h_
diff --git a/include/SDL3/SDL_guid.h b/include/SDL3/SDL_guid.h
index 7806d835cb83c..2f464c6757e0d 100644
--- a/include/SDL3/SDL_guid.h
+++ b/include/SDL3/SDL_guid.h
@@ -26,6 +26,8 @@
*
* A GUID is a 128-bit value that represents something that is uniquely
* identifiable by this value: "globally unique."
+ *
+ * SDL provides functions to convert a GUID to/from a string.
*/
#ifndef SDL_guid_h_
diff --git a/include/SDL3/SDL_intrin.h b/include/SDL3/SDL_intrin.h
index efba11d530d53..8444a3bbc2128 100644
--- a/include/SDL3/SDL_intrin.h
+++ b/include/SDL3/SDL_intrin.h
@@ -20,7 +20,7 @@
*/
/*
- * Header file for CPU intrinsics for SDL
+ * 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 44770972cbcc3..f10b3ec729c6c 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -25,7 +25,7 @@
* SDL joystick support.
*
* This is the lower-level joystick handling. If you want the simpler option,
- * where what buttons does what is well-defined, you should use the gamepad
+ * where what each button does is well-defined, you should use the gamepad
* API instead.
*
* The term "instance_id" is the current instantiation of a joystick device in
diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h
index f843a8070b8f7..f6505d19e9c37 100644
--- a/include/SDL3/SDL_keyboard.h
+++ b/include/SDL3/SDL_keyboard.h
@@ -23,6 +23,11 @@
* # CategoryKeyboard
*
* SDL keyboard management.
+ *
+ * Please refer to the Best Keyboard Practices document for details on how
+ * best to accept keyboard input in various types of programs:
+ *
+ * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
*/
#ifndef SDL_keyboard_h_
diff --git a/include/SDL3/SDL_keycode.h b/include/SDL3/SDL_keycode.h
index 77968bd0927a9..d1c474e3ae113 100644
--- a/include/SDL3/SDL_keycode.h
+++ b/include/SDL3/SDL_keycode.h
@@ -23,6 +23,11 @@
* # CategoryKeycode
*
* Defines constants which identify keyboard keys and modifiers.
+ *
+ * Please refer to the Best Keyboard Practices document for
+ * details on what this information means and how best to use it.
+ *
+ * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
*/
#ifndef SDL_keycode_h_
diff --git a/include/SDL3/SDL_loadso.h b/include/SDL3/SDL_loadso.h
index 53c496711c67c..11991788dfcb2 100644
--- a/include/SDL3/SDL_loadso.h
+++ b/include/SDL3/SDL_loadso.h
@@ -46,6 +46,11 @@
* not defined whether or not it goes into the global symbol namespace for
* the application. If it does and it conflicts with symbols in your code or
* other shared libraries, you will not get the results you expect. :)
+ * - Once a library is unloaded, all pointers into it obtained through
+ * SDL_LoadFunction() become invalid, even if the library is later reloaded.
+ * Don't unload a library if you plan to use these pointers in the future.
+ * Notably: beware of giving one of these pointers to atexit(), since it
+ * may call that pointer after the library unloads.
*/
#ifndef SDL_loadso_h_
diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h
index 3042bd858b11a..a5035830fe4d0 100644
--- a/include/SDL3/SDL_locale.h
+++ b/include/SDL3/SDL_locale.h
@@ -23,6 +23,12 @@
* # CategoryLocale
*
* SDL locale services.
+ *
+ * This provides a way to get a list of preferred locales (language plus
+ * country) for the user. There is exactly one function:
+ * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers
+ * documentation on all the strange ways humans might have configured their
+ * language settings.
*/
#ifndef SDL_locale_h
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index 047c6be94b575..152a2cc5c060c 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -35,6 +35,13 @@
*
* SDL will take care of platform specific details on how it gets called.
*
+ * This is also where an app can be configured to use the main callbacks,
+ * via the SDL_MAIN_USE_CALLBACKS macro.
+ *
+ * This is a "single-header library," which is to say that including this
+ * header inserts code into your program, and you should only include it
+ * once in most cases. SDL.h does not include this header automatically.
+ *
* For more information, see:
*
* https://wiki.libsdl.org/SDL3/README/main-functions
diff --git a/include/SDL3/SDL_scancode.h b/include/SDL3/SDL_scancode.h
index deda12fe13568..d0a0c2df62214 100644
--- a/include/SDL3/SDL_scancode.h
+++ b/include/SDL3/SDL_scancode.h
@@ -23,6 +23,11 @@
* # CategoryScancode
*
* Defines keyboard scancodes.
+ *
+ * Please refer to the Best Keyboard Practices document for
+ * details on what this information means and how best to use it.
+ *
+ * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
*/
#ifndef SDL_scancode_h_
diff --git a/include/SDL3/SDL_test.h b/include/SDL3/SDL_test.h
index e8468739136de..2cf83d8046620 100644
--- a/include/SDL3/SDL_test.h
+++ b/include/SDL3/SDL_test.h
@@ -20,8 +20,6 @@
*/
/**
- * \file SDL_test.h
- *
* 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_common.h b/include/SDL3/SDL_test_common.h
index aeffeb93b52bf..8b909311fd31a 100644
--- a/include/SDL3/SDL_test_common.h
+++ b/include/SDL3/SDL_test_common.h
@@ -20,8 +20,6 @@
*/
/**
- * \file SDL_test_common.h
- *
* 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 24bc9ee6e7fda..db2ae6c68cace 100644
--- a/include/SDL3/SDL_test_compare.h
+++ b/include/SDL3/SDL_test_compare.h
@@ -20,8 +20,6 @@
*/
/**
- * \file SDL_test_compare.h
- *
* 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_font.h b/include/SDL3/SDL_test_font.h
index 9d7b346eb75b1..bad949e0c8bf5 100644
--- a/include/SDL3/SDL_test_font.h
+++ b/include/SDL3/SDL_test_font.h
@@ -20,8 +20,6 @@
*/
/*
- * \file SDL_test_font.h
- *
* 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_harness.h b/include/SDL3/SDL_test_harness.h
index cea0db465f46c..925dc78caec57 100644
--- a/include/SDL3/SDL_test_harness.h
+++ b/include/SDL3/SDL_test_harness.h
@@ -20,8 +20,6 @@
*/
/**
- * \file SDL_test_harness.h
- *
* 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 ff798d63314f6..625d545dffb6d 100644
--- a/include/SDL3/SDL_test_log.h
+++ b/include/SDL3/SDL_test_log.h
@@ -20,8 +20,6 @@
*/
/**
- * \file SDL_test_log.h
- *
* 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 d751aab962bc1..a295439885ed2 100644
--- a/include/SDL3/SDL_test_md5.h
+++ b/include/SDL3/SDL_test_md5.h
@@ -20,8 +20,6 @@
*/
/**
- * \file SDL_test_md5.h
- *
* 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 16b2f63305f32..d1d0ef34aba66 100644
--- a/include/SDL3/SDL_test_memory.h
+++ b/include/SDL3/SDL_test_memory.h
@@ -20,8 +20,6 @@
*/
/**
- * \file SDL_test_memory.h
- *
* Memory tracking related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.