Add more links in SDL_dialog documentation

libsdl-org · May 3, 2024 · 06b9d88 · 06b9d88
1 parent 77f4ffc
commit 06b9d88
Showing 1 changed file with 34 additions and 16 deletions.
diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h
@@ -72,7 +72,7 @@ typedef struct SDL_DialogFileFilter
  * The filter argument is the index of the filter that was selected, or one
  * more than the size of the list (therefore the index of the terminating NULL
  * entry) if no filter was selected, or -1 if the platform or method doesn't
- * support fetching the selected filter or if an error occured.
+ * support fetching the selected filter.
  *
  * \since This datatype is available since SDL 3.0.0.
  *
@@ -101,14 +101,19 @@ typedef void(SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const
  * Depending on the platform, the user may be allowed to input paths that
  * don't yet exist.
  *
- * \param callback The function to be invoked when the user selects a file and
- *                 accepts, or the user 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
+ * \param callback An SDL_DialogFileCallback 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 occured. If an error occured, it
  *                 can be fetched with SDL_GetError(). The second argument is
- *                 the userdata pointer passed to the function.
+ *                 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.
  * \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.
@@ -123,6 +128,8 @@ typedef void(SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const
  *
  * \since This function is available since SDL 3.0.0.
  *
+ * \sa SDL_DialogFileCallback
+ * \sa SDL_DialogFileFilter
  * \sa SDL_ShowSaveFileDialog
  * \sa SDL_ShowOpenFolderDialog
  */
@@ -146,14 +153,19 @@ extern DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callb
  *
  * The chosen file may or may not already exist.
  *
- * \param callback The function to be invoked when the user selects a file and
- *                 accepts, or the user 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
+ * \param callback An SDL_DialogFileCallback 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 occured. If an error occured, it
  *                 can be fetched with SDL_GetError(). The second argument is
- *                 the userdata pointer passed to the function.
+ *                 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.
  * \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.
@@ -166,7 +178,10 @@ extern DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callb
  *
  * \since This function is available since SDL 3.0.0.
  *
+ * \sa SDL_DialogFileCallback
+ * \sa SDL_DialogFileFilter
  * \sa SDL_ShowOpenFileDialog
+ * \sa SDL_ShowOpenFolderDialog
  */
 extern DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, const char *default_location);
 
@@ -188,14 +203,15 @@ extern DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callb
  * Depending on the platform, the user may be allowed to input paths that
  * don't yet exist.
  *
- * \param callback The function to be invoked when the user selects a folder
- *                 and accepts, or the user 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
+ * \param callback An SDL_DialogFileCallback 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 occured. If an error occured, it
  *                 can be fetched with SDL_GetError(). The second argument is
- *                 the userdata pointer passed to the function.
+ *                 the userdata pointer passed to the function. The third
+ *                 argument is always -1 for SDL_ShowOpenFolderDialog.
  * \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.
@@ -207,7 +223,9 @@ extern DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callb
  *
  * \since This function is available since SDL 3.0.0.
  *
+ * \sa SDL_DialogFileCallback
  * \sa SDL_ShowOpenFileDialog
+ * \sa SDL_ShowSaveFileDialog
  */
 extern DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many);