Heavy work on improving category documentation.

Still more to go!

Reference Issue #9440.

include/SDL3/SDL.h

@@ -20,9 +20,12 @@
 */
 
 /**
- *  \file SDL.h
- *
  * 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_

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.
+ * - 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: do a debug build and just sprinkle around tests to check your
- * code!
+ * To use it: compile a debug build and just sprinkle around tests to check
+ * your code!
  */
 
 #ifndef SDL_assert_h_

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

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 = \

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_

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_

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.

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

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_

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.

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

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

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_

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_

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

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_

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_

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_

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

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

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_

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.

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.

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.

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.

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.

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.

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.

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.