From 7c08b049e864b3d7abd336b6b77fa57815e1487e Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 23 Mar 2021 15:36:12 -0400
Subject: [PATCH] headers: a few minor documentation corrections.
---
include/SDL_assert.h | 28 ++++++++++------------------
include/SDL_video.h | 2 --
2 files changed, 10 insertions(+), 20 deletions(-)
diff --git a/include/SDL_assert.h b/include/SDL_assert.h
index 6a5bc0006..a627b1786 100644
--- a/include/SDL_assert.h
+++ b/include/SDL_assert.h
@@ -189,6 +189,14 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
#define SDL_assert_always(condition) SDL_enabled_assert(condition)
+/**
+ * A callback that fires when an SDL assertion fails.
+ *
+ * \param data a pointer to the SDL_AssertData structure corresponding to the
+ * current assertion
+ * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
+ * \returns an SDL_AssertState value indicating how to handle the failure.
+ */
typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
const SDL_AssertData* data, void* userdata);
@@ -200,29 +208,13 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
* provide this, SDL will try to do the right thing, popping up a
* system-specific GUI dialog, and probably minimizing any fullscreen windows.
*
- * The function prototype for `handler` is:
- *
- * ```c
- * SDL_AssertState YourAssertionHandler(const SDL_AssertData* data, void* userdata)
- * ```
- *
- * where `YourAssertionHandler` is the name of your function and its
- * parameters are:
- *
- * - `data`: a pointer to the SDL_AssertData structure corresponding to the
- * current assertion
- * - `userdata`: what was passed as `userdata` to SDL_SetAssertionHandler()
- *
- * This callback should return an SDL_AssertState value indicating how to
- * handle the assertion failure.
- *
* This callback may fire from any thread, but it runs wrapped in a mutex, so
* it will only fire from one thread at a time.
*
* This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
*
- * \param handler the function to call when an assertion fails or NULL for the
- * default handler
+ * \param handler the SDL_AssertionHandler function to call when an assertion
+ * fails or NULL for the default handler
* \param userdata a pointer that is passed to `handler`
*
* \sa SDL_GetAssertionHandler
diff --git a/include/SDL_video.h b/include/SDL_video.h
index b9e3782ac..7a2c5042c 100644
--- a/include/SDL_video.h
+++ b/include/SDL_video.h
@@ -1074,8 +1074,6 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
/**
* Restore the size and position of a minimized or maximized window.
*
- * *You can add useful comments here*
- *
* \param window the window to restore
*
* \sa SDL_MaximizeWindow