From c486959e713d0ae45c648ac24dae8cde72e834c6 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 24 Mar 2021 10:47:03 -0400
Subject: [PATCH] headers: Fix up bullet lists, now that wikiheaders.pl can
handle them.
---
include/SDL.h | 2 +-
include/SDL_audio.h | 15 ++++-----------
include/SDL_blendmode.h | 32 +++++++++++---------------------
include/SDL_events.h | 16 ++++++----------
include/SDL_filesystem.h | 17 ++++++-----------
include/SDL_hints.h | 1 +
include/SDL_joystick.h | 11 +----------
include/SDL_messagebox.h | 2 --
include/SDL_mouse.h | 3 ---
include/SDL_platform.h | 4 ----
include/SDL_rwops.h | 2 --
include/SDL_system.h | 20 --------------------
include/SDL_video.h | 25 +++----------------------
13 files changed, 33 insertions(+), 117 deletions(-)
diff --git a/include/SDL.h b/include/SDL.h
index a69541679..f4576d619 100644
--- a/include/SDL.h
+++ b/include/SDL.h
@@ -118,7 +118,7 @@ extern "C" {
* events subsystem
* - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
* - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
- * initializes the joystick subsystem
+ * initializes the joystick subsystem
* - `SDL_INIT_EVENTS`: events subsystem
* - `SDL_INIT_EVERYTHING`: all of the above subsystems
* - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 99d8a2b8b..2c05d1755 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -300,12 +300,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
* With two notable exceptions:
*
* - If `obtained` is NULL, we use `desired` (and allow no changes), which
- * means desired will be modified to have the correct values for silence, etc,
- * and SDL will convert any differences between your app's specific request
- * and the hardware behind the scenes.
- *
+ * means desired will be modified to have the correct values for silence,
+ * etc, and SDL will convert any differences between your app's specific
+ * request and the hardware behind the scenes.
* - The return value is always success or failure, and not a device ID, which
- * means you can only have one device open at a time with this function.
+ * means you can only have one device open at a time with this function.
*
* \param desired an SDL_AudioSpec structure representing the desired output
* format. Please refer to the SDL_OpenAudioDevice documentation
@@ -464,9 +463,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
* When filling in the desired audio spec structure:
*
* - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
- *
* - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
- *
* - `desired->samples` is the desired size of the audio buffer, in
* _sample frames_ (with stereo output, two samples--left and right--would
* make a single sample frame). This number should be a power of two, and
@@ -477,13 +474,10 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
* processing and cannot fill the audio buffer in time. Note that the
* number of sample frames is directly related to time by the following
* formula: `ms = (sampleframes*1000)/freq`
- *
* - `desired->size` is the size in _bytes_ of the audio buffer, and is
* calculated by SDL_OpenAudioDevice(). You don't initialize this.
- *
* - `desired->silence` is the value used to set the buffer to silence,
* and is calculated by SDL_OpenAudioDevice(). You don't initialize this.
- *
* - `desired->callback` should be set to a function that will be called
* when the audio device is ready for more data. It is passed a pointer
* to the audio buffer, and the length in bytes of the audio buffer.
@@ -493,7 +487,6 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
* pointer here, and call SDL_QueueAudio() with some frequency, to queue
* more audio samples to be played (or for capture devices, call
* SDL_DequeueAudio() with some frequency, to obtain audio samples).
- *
* - `desired->userdata` is passed as the first parameter to your callback
* function. If you passed a NULL callback, this value is ignored.
*
diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h
index 919588a70..7627e324c 100644
--- a/include/SDL_blendmode.h
+++ b/include/SDL_blendmode.h
@@ -113,13 +113,9 @@ typedef enum
* `alphaOperation(src, dst)` can return one of the following:
*
* - `src + dst`
- *
* - `src - dst`
- *
* - `dst - src`
- *
* - `min(src, dst)`
- *
* - `max(src, dst)`
*
* The red, green, and blue components are always multiplied with the first,
@@ -140,28 +136,22 @@ typedef enum
* SDL_BlendMode enumeration.
*
* - **direct3d**: Supports `SDL_BLENDOPERATION_ADD` with all factors.
- *
* - **direct3d11**: Supports all operations with all factors. However, some
- * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
- * `SDL_BLENDOPERATION_MAXIMUM`.
- *
+ * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
+ * `SDL_BLENDOPERATION_MAXIMUM`.
* - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
- * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with
- * SDL 2.0.6.
- *
+ * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with
+ * SDL 2.0.6.
* - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
- * factors. Color and alpha factors need to be the same. OpenGL ES 1
- * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
- * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
- * operations being different from each other. May support color and alpha
- * factors being different from each other.
- *
+ * factors. Color and alpha factors need to be the same. OpenGL ES 1
+ * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
+ * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
+ * operations being different from each other. May support color and alpha
+ * factors being different from each other.
* - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
- * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations
- * with all factors.
- *
+ * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations
+ * with all factors.
* - **psp**: No custom blend mode support.
- *
* - **software**: No custom blend mode support.
*
* Some renderers do not provide an alpha component for the default render
diff --git a/include/SDL_events.h b/include/SDL_events.h
index a2f3e3c8e..6a04391fe 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -672,15 +672,13 @@ typedef enum
* `action` may be any of the following:
*
* - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of
- * the event queue.
- *
+ * the event queue.
* - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
- * within the specified minimum and maximum type, will be returned to the
- * caller and will _not_ be removed from the queue.
- *
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will _not_ be removed from the queue.
* - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
- * within the specified minimum and maximum type, will be returned to the
- * caller and will be removed from the queue.
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will be removed from the queue.
*
* You may have to call SDL_PumpEvents() before calling this function.
* Otherwise, the events may not be ready to be filtered when you call
@@ -1050,10 +1048,8 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
* `state` may be any of the following:
*
* - `SDL_QUERY`: returns the current processing state of the specified event
- *
* - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
- * from the event queue and will not be filtered
- *
+ * from the event queue and will not be filtered
* - `SDL_ENABLE`: the event will be processed normally
*
* \param type the type of event; see SDL_EventType for details
diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h
index 55c93eee9..d06dbe9ed 100644
--- a/include/SDL_filesystem.h
+++ b/include/SDL_filesystem.h
@@ -54,13 +54,11 @@ extern "C" {
* application in /Applications/SDLApp/MyApp.app):
*
* - `resource`: bundle resource directory (the default). For example:
- * `/Applications/SDLApp/MyApp.app/Contents/Resources`
- *
+ * `/Applications/SDLApp/MyApp.app/Contents/Resources`
* - `bundle`: the Bundle directory. Fpr example:
- * `/Applications/SDLApp/MyApp.app/`
- *
+ * `/Applications/SDLApp/MyApp.app/`
* - `parent`: the containing directory of the bundle. For example:
- * `/Applications/SDLApp/`
+ * `/Applications/SDLApp/`
*
* The returned path is guaranteed to end with a path separator ('\' on
* Windows, '/' on most other platforms).
@@ -111,15 +109,12 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
* follow these rules:
*
* - Try to use the same org string (_including case-sensitivity_) for all
- * your applications that use this function.
- *
+ * your applications that use this function.
* - Always use a unique app string for each one, and make sure it never
- * changes for an app once you've decided on it.
- *
+ * changes for an app once you've decided on it.
* - Unicode characters are legal, as long as it's UTF-8 encoded, but...
- *
* - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
- * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
+ * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
*
* The returned path is guaranteed to end with a path separator ('\' on
* Windows, '/' on most other platforms).
diff --git a/include/SDL_hints.h b/include/SDL_hints.h
index 90e45de98..f7acfffce 100644
--- a/include/SDL_hints.h
+++ b/include/SDL_hints.h
@@ -1319,6 +1319,7 @@ extern "C" {
*
* Since it's driver-specific, it's only supported where possible and
* implemented. Currently supported the following drivers:
+ *
* - KMSDRM (kmsdrm)
* - Raspberry Pi (raspberrypi)
*/
diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h
index cfdbcd8db..006d5fdce 100644
--- a/include/SDL_joystick.h
+++ b/include/SDL_joystick.h
@@ -666,26 +666,17 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j
* The returned value will be one of the following positions:
*
* - `SDL_HAT_CENTERED`
- *
* - `SDL_HAT_UP`
- *
* - `SDL_HAT_RIGHT`
- *
* - `SDL_HAT_DOWN`
- *
* - `SDL_HAT_LEFT`
- *
* - `SDL_HAT_RIGHTUP`
- *
* - `SDL_HAT_RIGHTDOWN`
- *
* - `SDL_HAT_LEFTUP`
- *
* - `SDL_HAT_LEFTDOWN`
*
* \param joystick an SDL_Joystick structure containing joystick information
- * \param hat the hat index to get the state from; hat indices start at index
- * 0
+ * \param hat the hat index to get the state from; indices start at index 0
* \returns the current hat position.
*
* \sa SDL_JoystickNumHats
diff --git a/include/SDL_messagebox.h b/include/SDL_messagebox.h
index 02f546902..c2aef70fa 100644
--- a/include/SDL_messagebox.h
+++ b/include/SDL_messagebox.h
@@ -148,9 +148,7 @@ extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *message
* `flags` may be any of the following:
*
* - `SDL_MESSAGEBOX_ERROR`: error dialog
- *
* - `SDL_MESSAGEBOX_WARNING`: warning dialog
- *
* - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
*
* This function should be called on the thread that created the parent
diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h
index 3bfc4d195..2704c0d6e 100644
--- a/include/SDL_mouse.h
+++ b/include/SDL_mouse.h
@@ -255,11 +255,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
* The cursor is created in black and white according to the following:
*
* - data=0, mask=1: white
- *
* - data=1, mask=1: black
- *
* - data=0, mask=1: transparent
- *
* - data=1, mask=0: inverted color if possible, black if not.
*
* Cursors created with this function must be freed with SDL_FreeCursor().
diff --git a/include/SDL_platform.h b/include/SDL_platform.h
index ea3aadd6a..ebaa25242 100644
--- a/include/SDL_platform.h
+++ b/include/SDL_platform.h
@@ -191,13 +191,9 @@ extern "C" {
* Here are the names returned for some (but not all) supported platforms:
*
* - "Windows"
- *
* - "Mac OS X"
- *
* - "Linux"
- *
* - "iOS"
- *
* - "Android"
*
* \returns the name of the platform. If the correct platform name is not
diff --git a/include/SDL_rwops.h b/include/SDL_rwops.h
index 88003e403..09fe33b75 100644
--- a/include/SDL_rwops.h
+++ b/include/SDL_rwops.h
@@ -201,9 +201,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
* `whence` may be any of the following values:
*
* - `RW_SEEK_SET`: seek from the beginning of data
- *
* - `RW_SEEK_CUR`: seek relative to current read point
- *
* - `RW_SEEK_END`: seek relative to the end of data
*
* If this stream can not seek, it will return -1.
diff --git a/include/SDL_system.h b/include/SDL_system.h
index 753272e5d..6fea7d30e 100644
--- a/include/SDL_system.h
+++ b/include/SDL_system.h
@@ -197,45 +197,25 @@ extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
* Query Android API level of the current device.
*
* - API level 30: Android 11
- *
* - API level 29: Android 10
- *
* - API level 28: Android 9
- *
* - API level 27: Android 8.1
- *
* - API level 26: Android 8.0
- *
* - API level 25: Android 7.1
- *
* - API level 24: Android 7.0
- *
* - API level 23: Android 6.0
- *
* - API level 22: Android 5.1
- *
* - API level 21: Android 5.0
- *
* - API level 20: Android 4.4W
- *
* - API level 19: Android 4.4
- *
* - API level 18: Android 4.3
- *
* - API level 17: Android 4.2
- *
* - API level 16: Android 4.1
- *
* - API level 15: Android 4.0.3
- *
* - API level 14: Android 4.0
- *
* - API level 13: Android 3.2
- *
* - API level 12: Android 3.1
- *
* - API level 11: Android 3.0
- *
* - API level 10: Android 2.3.3
*
* \returns Android API level.
diff --git a/include/SDL_video.h b/include/SDL_video.h
index 7a2c5042c..f803adf23 100644
--- a/include/SDL_video.h
+++ b/include/SDL_video.h
@@ -469,13 +469,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
* The display modes are sorted in this priority:
*
* - width -> largest to smallest
- *
* - height -> largest to smallest
- *
* - bits per pixel -> more colors to fewer colors
- *
* - packed pixel layout -> largest to smallest
- *
* - refresh rate -> highest to lowest
*
* \param displayIndex the index of the display to query
@@ -619,29 +615,18 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
* `flags` may be any of the following OR'd together:
*
* - `SDL_WINDOW_FULLSCREEN`: fullscreen window
- *
- * - `SDL_WINDOW_FULLSCREEN_DESKTOP: fullscreen window at desktop resolution
- *
+ * - `SDL_WINDOW_FULLSCREEN_DESKTOP`: fullscreen window at desktop resolution
* - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context
- *
* - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance
- *
* - `SDL_WINDOW_METAL`: window usable with a Metal instance
- *
* - `SDL_WINDOW_HIDDEN`: window is not visible
- *
* - `SDL_WINDOW_BORDERLESS`: no window decoration
- *
* - `SDL_WINDOW_RESIZABLE`: window can be resized
- *
* - `SDL_WINDOW_MINIMIZED`: window is minimized
- *
* - `SDL_WINDOW_MAXIMIZED`: window is maximized
- *
* - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus
- *
* - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if
- * supported (>= SDL 2.0.1)
+ * supported (>= SDL 2.0.1)
*
* `SDL_WINDOW_SHOWN` is ignored by SDL_CreateWindow(). The SDL_Window is
* implicitly shown if SDL_WINDOW_HIDDEN is not set. `SDL_WINDOW_SHOWN` may be
@@ -1594,7 +1579,7 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
* There are some quirks to looking up OpenGL functions that require some
* extra care from the application. If you code carefully, you can handle
* these quirks without any platform-specific code, though:
-
+ *
* - On Windows, function pointers are specific to the current GL context;
* this means you need to have created a GL context and made it current before
* calling SDL_GL_GetProcAddress(). If you recreate your context or create a
@@ -1604,7 +1589,6 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
* but it is still the way the wgl API is documented to work and you should
* expect crashes if you don't respect it. Store a copy of the function
* pointers that comes and goes with context lifespan.
- *
* - On X11, function pointers returned by this function are valid for any
* context, and can even be looked up before a context is created at all. This
* means that, for at least some common OpenGL implementations, if you look up
@@ -1614,17 +1598,14 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
* the appropriate extension with SDL_GL_ExtensionSupported(), or verifying
* that the version of OpenGL you're using offers the function as core
* functionality.
- *
* - Some OpenGL drivers, on all platforms, *will* return NULL if a function
* isn't supported, but you can't count on this behavior. Check for extensions
* you use, and if you get a NULL anyway, act as if that extension wasn't
* available. This is probably a bug in the driver, but you can code
* defensively for this scenario anyhow.
- *
* - Just because you're on Linux/Unix, don't assume you'll be using X11.
* Next-gen display servers are waiting to replace it, and may or may not make
* the same promises about function pointers.
- *
* - OpenGL function pointers must be declared `APIENTRY` as in the example
* code. This will ensure the proper calling convention is followed on
* platforms where this matters (Win32) thereby avoiding stack corruption.