From ecae3789abe521277a3a287a41c2d1e4fbaadc09 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 20 Nov 2024 23:41:37 -0500
Subject: [PATCH] SDL_dialog.h: Remove verbose docs on callback param from
several functions.
In the wiki, one can click on SDL_DialogFileCallback for these details, or
grep for the symbol in the headers to find the information.
Fixes #11504.
---
include/SDL3/SDL_dialog.h | 40 +++++++--------------------------------
1 file changed, 7 insertions(+), 33 deletions(-)
diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h
index 5fe628298cc08..6a59f1f7004de 100644
--- a/include/SDL3/SDL_dialog.h
+++ b/include/SDL3/SDL_dialog.h
@@ -76,7 +76,7 @@ typedef struct SDL_DialogFileFilter
* is a null-terminated list of pointers to C strings, each containing a
* path.
*
- * The filelist argument does not need to be freed; it will automatically be
+ * The filelist argument should not be freed; it will automatically be
* freed when the callback returns.
*
* The filter argument is the index of the filter that was selected, or -1 if
@@ -118,19 +118,9 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons
* requires an event-handling loop. Apps that do not use SDL to handle events
* should add a call to SDL_PumpEvents in their main loop.
*
- * \param callback an SDL_DialogFileCallback to be invoked when the user
+ * \param callback a function pointer to be invoked when the user
* selects a file and accepts, or cancels the dialog, or an
- * error occurs. The first argument is a null-terminated list
- * of C strings, representing the paths chosen by the user.
- * The list will be empty if the user canceled the dialog, and
- * it will be NULL if an error occurred. If an error occurred,
- * it can be fetched with SDL_GetError(). The second argument
- * is the userdata pointer passed to the function. The third
- * argument is the index of the filter selected by the user,
- * or one past the index of the last filter (therefore the
- * index of the terminating NULL filter) if no filter was
- * chosen, or -1 if the platform does not support detecting
- * the selected filter.
+ * error occurs.
* \param userdata an optional pointer to pass extra data to the callback when
* it will be invoked.
* \param window the window that the dialog should be modal for, may be NULL.
@@ -175,19 +165,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c
* requires an event-handling loop. Apps that do not use SDL to handle events
* should add a call to SDL_PumpEvents in their main loop.
*
- * \param callback an SDL_DialogFileCallback to be invoked when the user
+ * \param callback a function pointer to be invoked when the user
* selects a file and accepts, or cancels the dialog, or an
- * error occurs. The first argument is a null-terminated list
- * of C strings, representing the paths chosen by the user.
- * The list will be empty if the user canceled the dialog, and
- * it will be NULL if an error occurred. If an error occurred,
- * it can be fetched with SDL_GetError(). The second argument
- * is the userdata pointer passed to the function. The third
- * argument is the index of the filter selected by the user,
- * or one past the index of the last filter (therefore the
- * index of the terminating NULL filter) if no filter was
- * chosen, or -1 if the platform does not support detecting
- * the selected filter.
+ * error occurs.
* \param userdata an optional pointer to pass extra data to the callback when
* it will be invoked.
* \param window the window that the dialog should be modal for, may be NULL.
@@ -230,15 +210,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c
* requires an event-handling loop. Apps that do not use SDL to handle events
* should add a call to SDL_PumpEvents in their main loop.
*
- * \param callback an SDL_DialogFileCallback to be invoked when the user
+ * \param callback a function pointer to be invoked when the user
* selects a file and accepts, or cancels the dialog, or an
- * error occurs. The first argument is a null-terminated list
- * of C strings, representing the paths chosen by the user.
- * The list will be empty if the user canceled the dialog, and
- * it will be NULL if an error occurred. If an error occurred,
- * it can be fetched with SDL_GetError(). The second argument
- * is the userdata pointer passed to the function. The third
- * argument is always -1 for SDL_ShowOpenFolderDialog.
+ * error occurs.
* \param userdata an optional pointer to pass extra data to the callback when
* it will be invoked.
* \param window the window that the dialog should be modal for, may be NULL.