From a216408bf040fc5e49baa66daeeb53690358068d Mon Sep 17 00:00:00 2001
From: PB <pbfordev@gmail.com>
Date: Thu, 22 Aug 2024 16:50:25 +0200
Subject: [PATCH] Improve documentation for convenience input functions

In wxDirSelector, provide the correct default argument for
the wxDirDialog style parameter, change the path parameter
name to match the implementation, and fix the example code.

Provide information about wxFD_ flags used by wxLoadFileSelector()
and wxSaveFileSelector().

Add missing default arguments for wxGetColourFromUser() and wxGetFontFromUser() parameters.

Improve formatting by using @c where appropriate.
---
 interface/wx/colordlg.h | 4 ++--
 interface/wx/dirdlg.h   | 8 ++++----
 interface/wx/filedlg.h  | 8 ++++++--
 interface/wx/fontdlg.h  | 4 ++--
 4 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/interface/wx/colordlg.h b/interface/wx/colordlg.h
index d9001608cf..ca6fba0884 100644
--- a/interface/wx/colordlg.h
+++ b/interface/wx/colordlg.h
@@ -158,8 +158,8 @@ wxEventType wxEVT_COLOUR_CHANGED;
 
     @header{wx/colordlg.h}
 */
-wxColour wxGetColourFromUser(wxWindow* parent,
-                             const wxColour& colInit,
+wxColour wxGetColourFromUser(wxWindow* parent = nullptr,
+                             const wxColour& colInit = wxNullColour,
                              const wxString& caption = wxEmptyString,
                              wxColourData* data = nullptr);
 
diff --git a/interface/wx/dirdlg.h b/interface/wx/dirdlg.h
index 759b2b7ea4..0fc5d00867 100644
--- a/interface/wx/dirdlg.h
+++ b/interface/wx/dirdlg.h
@@ -167,13 +167,13 @@ public:
 /**
     Pops up a directory selector dialog. The arguments have the same meaning
     as those of wxDirDialog::wxDirDialog(). The message is displayed at the
-    top, and the default_path, if specified, is set as the initial selection.
+    top, and the @a defaultPath, if specified, is set as the initial selection.
 
     The application must check for an empty return value (if the user pressed
     Cancel). For example:
 
     @code
-    const wxString& dir = wxDirSelector("Choose a folder");
+    const wxString dir = wxDirSelector("Choose a folder");
     if ( !dir.empty() )
     {
         ...
@@ -183,8 +183,8 @@ public:
     @header{wx/dirdlg.h}
 */
 wxString wxDirSelector(const wxString& message = wxDirSelectorPromptStr,
-                       const wxString& default_path = wxEmptyString,
-                       long style = 0,
+                       const wxString& defaultPath = wxEmptyString,
+                       long style = wxDD_DEFAULT_STYLE,
                        const wxPoint& pos = wxDefaultPosition,
                        wxWindow* parent = nullptr);
 
diff --git a/interface/wx/filedlg.h b/interface/wx/filedlg.h
index 6184b1e15c..90d2c73264 100644
--- a/interface/wx/filedlg.h
+++ b/interface/wx/filedlg.h
@@ -495,9 +495,9 @@ public:
     default filename will be supplied. The wildcard determines what files are
     displayed in the file selector, and file extension supplies a type
     extension for the required filename. Flags may be a combination of
-    wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
+    @c wxFD_OPEN, @c wxFD_SAVE, @c wxFD_OVERWRITE_PROMPT or @c wxFD_FILE_MUST_EXIST.
 
-    @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
+    @note @c wxFD_MULTIPLE can only be used with wxFileDialog and not here since
           this function only returns a single file name.
 
     Both the Unix and Windows versions implement a wildcard filter. Typing a
@@ -555,6 +555,8 @@ wxString wxFileSelectorEx(const wxString& message = wxFileSelectorPromptStr,
 /**
     Shows a file dialog asking the user for a file name for opening a file.
 
+    The file dialog will have @c wxFD_FILE_MUST_EXIST flag set.
+
     @see wxFileSelector(), wxFileDialog
 
     @header{wx/filedlg.h}
@@ -567,6 +569,8 @@ wxString wxLoadFileSelector(const wxString& what,
 /**
     Shows a file dialog asking the user for a file name for saving a file.
 
+    The file dialog will not have @c wxFD_OVERWRITE_PROMPT flag set.
+
     @see wxFileSelector(), wxFileDialog
 
     @header{wx/filedlg.h}
diff --git a/interface/wx/fontdlg.h b/interface/wx/fontdlg.h
index 6abd5605a0..16c7021790 100644
--- a/interface/wx/fontdlg.h
+++ b/interface/wx/fontdlg.h
@@ -97,8 +97,8 @@ public:
 
     @header{wx/fontdlg.h}
 */
-wxFont wxGetFontFromUser(wxWindow* parent,
-                         const wxFont& fontInit,
+wxFont wxGetFontFromUser(wxWindow* parent = nullptr,
+                         const wxFont& fontInit = wxNullFont,
                          const wxString& caption = wxEmptyString);
 
 ///@}