Doc: Improve documentation for QFileDialog::Option

Do not add new paragraphs in the \value description,
which breaks the generated HTML table. Instead, use \br
more often to break overly long lines.

Replace 'option is only valid' or 'supported' by
'effective' and 'used'; if an enum doesn't apply to a
dialog or platform it will just be ignored, but it's
OK to set it.

Fix link to DontUseCustomDirectoryIcons enum.

Pick-to: 6.5 6.6 6.7
Task-number: QTBUG-119551
Change-Id: Iac86a85c7b3b402997fa14f4c4e2fa7111c62e9e
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

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
 */
 
 /*!