1 files changed, 27 insertions, 23 deletions
diff --git a/src/widgets/dialogs/qfiledialog.cpp b/src/widgets/dialogs/qfiledialog.cpp
index 6439952abd..1824aea03e 100644
--- a/src/widgets/dialogs/qfiledialog.cpp
+++ b/src/widgets/dialogs/qfiledialog.cpp
@@ -185,38 +185,42 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
 /*!
     \enum QFileDialog::Option
 
-    \value ShowDirsOnly Only show directories in the file dialog. By
-    default both files and directories are shown. (Valid only in the
-    \l Directory file mode.)
+    Options that influence the behavior of the dialog.
 
-    \value DontResolveSymlinks Don't resolve symlinks in the file
-    dialog. By default symlinks are resolved.
+    \value ShowDirsOnly Only show directories. By
+    default, both files and directories are shown.\br
+    This option is only effective in the \l Directory file mode.
 
-    \value DontConfirmOverwrite Don't ask for confirmation if an
-    existing file is selected. By default, confirmation is requested.
-    (Valid only if \l acceptMode is \l {QFileDialog::}{AcceptSave}).
-
-    Note: This option is not supported on macOS when using the
-    native file dialog.
+    \value DontResolveSymlinks Don't resolve symlinks.
+    By default, symlinks are resolved.
 
-    \value DontUseNativeDialog Don't use the native file dialog. By
-    default, the native file dialog is used unless you use a subclass
-    of QFileDialog that contains the Q_OBJECT macro, or the platform
-    does not have a native dialog of the type that you require.
+    \value DontConfirmOverwrite Don't ask for confirmation if an
+    existing file is selected. By default, confirmation is requested.\br
+    This option is only effective if \l acceptMode is \l {QFileDialog::}{AcceptSave}).
+    It is furthermore not used on macOS for native file dialogs.
 
-    \b{Note:} This option must be set before changing dialog properties
-    or showing the dialog.
+    \value DontUseNativeDialog Don't use a platform-native file dialog,
+    but the widget-based one provided by Qt.\br
+    By default, a native file dialog is shown unless you use a subclass
+    of QFileDialog that contains the Q_OBJECT macro or the platform
+    does not have a native dialog of the type that you require.\br
+    For the option to be effective, you must set it before changing
+    other properties of the dialog, or showing the dialog.
 
-    \value ReadOnly Indicates that the model is readonly.
+    \value ReadOnly Indicates that the model is read-only.
 
     \value HideNameFilterDetails Indicates if the file name filter details are
     hidden or not.
 
-    \value DontUseCustomDirectoryIcons Always use the default directory icon.
-    Some platforms allow the user to set a different icon. Custom icon lookup
-    causes a big performance impact over network or removable drives.
-    Setting this will enable the QFileIconProvider::DontUseCustomDirectoryIcons
-    option in the icon provider. This enum value was added in Qt 5.2.
+    \value DontUseCustomDirectoryIcons Always use the default directory icon.\br
+    Some platforms allow the user to set a different icon, but custom icon lookup
+    might cause significant performance issues over network or removable drives.\br
+    Setting this will enable the
+    \l{QAbstractFileIconProvider::}{DontUseCustomDirectoryIcons}
+    option in \l{iconProvider()}.\br
+    This enum value was added in Qt 5.2.
+
+    \sa options, testOption
 */
 
 /*!