From a2ffd37c48a4e947811747168c7698f657ddbc68 Mon Sep 17 00:00:00 2001
From: PB <pbfordev@gmail.com>
Date: Sat, 24 Aug 2024 20:16:45 +0200
Subject: [PATCH] Improve wxDirDialog documentation

Remove outdated information about special meaning of wxRESIZE_BORDER
style flag on Windows.

Add a reference to ::wxDirSelector() and wxDirPickerCtrl.

Improve formatting by using @c where appropriate and fix few typos.

In the common dialogs overview, add that wxDirDialog can be used to
select also mutiple directories.
---
 docs/doxygen/overviews/commondialogs.h |  4 +--
 interface/wx/dirdlg.h                  | 37 ++++++++------------------
 2 files changed, 13 insertions(+), 28 deletions(-)

diff --git a/docs/doxygen/overviews/commondialogs.h b/docs/doxygen/overviews/commondialogs.h
index ee6a93ff2b..3a5580a724 100644
--- a/docs/doxygen/overviews/commondialogs.h
+++ b/docs/doxygen/overviews/commondialogs.h
@@ -182,8 +182,8 @@ description for each, such as:
 
 Classes: wxDirDialog
 
-This dialog shows a directory selector dialog, allowing the user to select a
-single directory.
+This dialog shows a directory selector dialog, allowing the user to select
+one or multiple directories.
 
 
 
diff --git a/interface/wx/dirdlg.h b/interface/wx/dirdlg.h
index 0fc5d00867..f1e79c6882 100644
--- a/interface/wx/dirdlg.h
+++ b/interface/wx/dirdlg.h
@@ -37,12 +37,12 @@ const char wxDirDialogNameStr[] = "wxDirCtrl";
 
     @beginStyleTable
     @style{wxDD_DEFAULT_STYLE}
-           Equivalent to a combination of wxDEFAULT_DIALOG_STYLE and
-           wxRESIZE_BORDER.
+           Equivalent to a combination of @c wxDEFAULT_DIALOG_STYLE and
+           @c wxRESIZE_BORDER.
     @style{wxDD_DIR_MUST_EXIST}
            The dialog will allow the user to choose only an existing folder.
            When this style is not given, a "Create new directory" button is
-           added to the dialog (on Windows) or some other way is provided to
+           added to the dialog or some other way is provided to
            the user to type the name of a new folder.
     @style{wxDD_CHANGE_DIR}
            Change the current working directory to the directory chosen by the
@@ -50,36 +50,21 @@ const char wxDirDialogNameStr[] = "wxDirCtrl";
            This flag cannot be used with the @c wxDD_MULTIPLE style.
     @style{wxDD_MULTIPLE}
            Allow the user to select multiple directories.
-           This flag is only available since wxWidgets 3.1.4
+           This flag is only available since wxWidgets 3.1.4.
     @style{wxDD_SHOW_HIDDEN}
            Show hidden and system folders.
-           This flag is only available since wxWidgets 3.1.4
+           This flag is only available since wxWidgets 3.1.4.
     @endStyleTable
 
-    Notice that @c wxRESIZE_BORDER has special side effect under Windows
-    where two different directory selection dialogs are available and this
-    style also implicitly selects the new version as the old one always has
-    fixed size. As the new version is almost always preferable, it is
-    recommended that @c wxRESIZE_BORDER style be always used.
-    This is the case if the dialog is created with the default style value but
-    if you need to use any additional styles you should still specify @c
-    wxDD_DEFAULT_STYLE unless you explicitly need to use the old dialog version
-    under Windows. E.g. do
-    @code
-        wxDirDialog dlg(nullptr, "Choose input directory", "",
-                        wxDD_DEFAULT_STYLE | wxDD_DIR_MUST_EXIST);
-    @endcode
-    instead of just using @c wxDD_DIR_MUST_EXIST style alone.
-
-    @remarks MacOS 10.11+ does not display a title bar on the dialog. Use SetMessage()
+    @remarks macOS 10.11+ does not display a title bar on the dialog. Use SetMessage()
              to change the string displayed to the user at the top of the dialog after creation.
-             The SetTitle() method is provided for compatibility with pre-10.11 MacOS versions
+             The SetTitle() method is provided for compatibility with pre-10.11 macOS versions
              that do still support displaying the title bar.
 
     @library{wxcore}
     @category{cmndlg}
 
-    @see @ref overview_cmndlg_dir, wxFileDialog
+    @see @ref overview_cmndlg_dir, ::wxDirSelector(), wxDirPickerCtrl, wxFileDialog
 */
 class wxDirDialog : public wxDialog
 {
@@ -94,7 +79,7 @@ public:
         @param defaultPath
             The default path, or the empty string.
         @param style
-            The dialog style. See wxDirDialog
+            The dialog style, see @c wxDD_* styles for more info.
         @param pos
             Dialog position. Ignored under Windows.
         @param size
@@ -149,8 +134,8 @@ public:
     virtual void SetPath(const wxString& path);
 
     /**
-        Shows the dialog, returning wxID_OK if the user pressed OK, and
-        wxID_CANCEL otherwise.
+        Shows the dialog, returning @c wxID_OK if the user pressed OK, and
+        @c wxID_CANCEL otherwise.
     */
     int ShowModal();
 };