Doc - cleaning up some documentation for QFileDialog and obsolete

documentation.

getOpenFileNames() and getExistingDirectory() mentioned that the dir
parameter was ignored. This is no longer the case. This bit was reviewed
by nrc, the other fixes were just cleanups.

Task-number: 252223
Reviewed-by: nrc

1 files changed, 129 insertions, 134 deletions

diff --git a/src/gui/dialogs/qfiledialog.cpp b/src/gui/dialogs/qfiledialog.cpp
index d786f3e..073c25b 100644
--- a/src/gui/dialogs/qfiledialog.cpp
+++ b/src/gui/dialogs/qfiledialog.cpp
@@ -1538,52 +1538,51 @@ extern QString qt_win_get_existing_directory(const QFileDialogArgs &args);
 #endif
 
 /*!
-  This is a convenience static function that returns an existing file
-  selected by the user. If the user presses Cancel, it returns a null
-  string.
+    This is a convenience static function that returns an existing file
+    selected by the user. If the user presses Cancel, it returns a null string.
 
-  \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 8
+    \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 8
 
-  The function creates a modal file dialog with the given \a parent widget.
-  If the parent is not 0, the dialog will be shown centered over the
-  parent widget.
+    The function creates a modal file dialog with the given \a parent widget.
+    If \a parent is not 0, the dialog will be shown centered over the parent
+    widget.
 
-  The file dialog's working directory will be set to \a dir.  If \a
-  dir includes a file name, the file will be selected. Only files
-  that match the given \a filter are shown. The filter selected is
-  set to \a selectedFilter. The parameters \a dir, \a
-  selectedFilter, and \a filter may be empty strings. If you want
-  multiple filters, separate them with ';;', for example:
+    The file dialog's working directory will be set to \a dir. If \a dir
+    includes a file name, the file will be selected. Only files that match the
+    given \a filter are shown. The filter selected is set to \a selectedFilter.
+    The parameters \a dir, \a selectedFilter, and \a filter may be empty
+    strings. If you want multiple filters, separate them with ';;', for
+    example:
 
-  \code
+    \code
     "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
-  \endcode
+    \endcode
 
-  The \a options argument holds various
-  options about how to run the dialog, see the QFileDialog::Option enum for
-  more information on the flags you can pass.
+    The \a options argument holds various options about how to run the dialog,
+    see the QFileDialog::Option enum for more information on the flags you can
+    pass.
 
-  The dialog's caption is set to \a caption. If \a caption is not
-  specified then a default caption will be used.
+    The dialog's caption is set to \a caption. If \a caption is not specified
+    then a default caption will be used.
 
-  Under Windows and Mac OS X, this static function will use the native
-  file dialog and not a QFileDialog.
+    On Windows and Mac OS X, this static function will use the native file
+    dialog and not a QFileDialog.
 
-  Note that on Windows the dialog will spin a blocking modal event loop
-  that will not dispatch any QTimers, and if parent is not 0 then it will
-  position the dialog just under the parent's title bar.
+    On Windows the dialog will spin a blocking modal event loop that will not
+    dispatch any QTimers, and if \a parent is not 0 then it will position the
+    dialog just below the parent's title bar.
 
-  Under Unix/X11, the normal behavior of the file dialog is to resolve
-  and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
-  \c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
-  entering \c{/usr/tmp}. If \a options includes DontResolveSymlinks,
-  the file dialog will treat symlinks as regular directories.
+    On Unix/X11, the normal behavior of the file dialog is to resolve and
+    follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
+    the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If
+    \a options includes DontResolveSymlinks, the file dialog will treat
+    symlinks as regular directories.
 
-  \warning Do not delete \a parent during the execution of the dialog.
-           If you want to do this, you should create the dialog
-           yourself using one of the QFileDialog constructors.
+    \warning Do not delete \a parent during the execution of the dialog. If you
+    want to do this, you should create the dialog yourself using one of the
+    QFileDialog constructors.
 
-  \sa getOpenFileNames(), getSaveFileName(), getExistingDirectory()
+    \sa getOpenFileNames(), getSaveFileName(), getExistingDirectory()
 */
 QString QFileDialog::getOpenFileName(QWidget *parent,
                                const QString &caption,
@@ -1626,54 +1625,53 @@ QString QFileDialog::getOpenFileName(QWidget *parent,
 }
 
 /*!
-  This is a convenience static function that will return one or more
-  existing files selected by the user.
+    This is a convenience static function that will return one or more existing
+    files selected by the user.
 
-  \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 9
+    \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 9
 
-  This function creates a modal file dialog with the given \a parent
-  widget. If the parent is not 0, the dialog will be shown centered
-  over the parent widget.
+    This function creates a modal file dialog with the given \a parent widget.
+    If \a parent is not 0, the dialog will be shown centered over the parent
+    widget.
 
-  The file dialog's working directory will be set to \a dir. If \a
-  dir includes a file name, the file will be selected. The filter
-  is set to \a filter so that only those files which match the filter
-  are shown. The filter selected is set to \a selectedFilter. The parameters
-  \a dir, \a selectedFilter and \a filter may be empty strings. If you
-  need multiple filters, separate them with ';;', for instance:
+    The file dialog's working directory will be set to \a dir. If \a dir
+    includes a file name, the file will be selected. The filter is set to
+    \a filter so that only those files which match the filter are shown. The
+    filter selected is set to \a selectedFilter. The parameters \a dir,
+    \a selectedFilter and \a filter may be empty strings. If you need multiple
+    filters, separate them with ';;', for instance:
 
-  \code
+    \code
     "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
-  \endcode
+    \endcode
 
-  The dialog's caption is set to \a caption. If \a caption is not
-  specified then a default caption will be used.
+    The dialog's caption is set to \a caption. If \a caption is not specified
+    then a default caption will be used.
 
-  Under Windows and Mac OS X, this static function will use the native
-  file dialog and not a QFileDialog. On Mac OS X, the \a dir argument
-  is ignored, the native dialog always displays the last visited directory.
+    On Windows and Mac OS X, this static function will use the native file
+    dialog and not a QFileDialog.
 
-  Note that on Windows the dialog will spin a blocking modal event loop
-  that will not dispatch any QTimers, and if parent is not 0 then it will
-  position the dialog just under the parent's title bar.
+    On Windows the dialog will spin a blocking modal event loop that will not
+    dispatch any QTimers, and if \a parent is not 0 then it will position the
+    dialog just below the parent's title bar.
 
-  Under Unix/X11, the normal behavior of the file dialog is to resolve
-  and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
-  \c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
-  entering \c{/usr/tmp}. The \a options argument holds various
-  options about how to run the dialog, see the QFileDialog::Option enum for
-  more information on the flags you can pass.
+    On Unix/X11, the normal behavior of the file dialog is to resolve and
+    follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
+    the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}.
+    The \a options argument holds various options about how to run the dialog,
+    see the QFileDialog::Option enum for more information on the flags you can
+    pass.
 
-  Note that if you want to iterate over the list of files, you should
-  iterate over a copy. For example:
+    \note If you want to iterate over the list of files, you should iterate
+    over a copy. For example:
 
     \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 10
 
-  \warning Do not delete \a parent during the execution of the dialog.
-           If you want to do this, you should create the dialog
-           yourself using one of the QFileDialog constructors.
+    \warning Do not delete \a parent during the execution of the dialog. If you
+    want to do this, you should create the dialog yourself using one of the
+    QFileDialog constructors.
 
-  \sa getOpenFileName(), getSaveFileName(), getExistingDirectory()
+    \sa getOpenFileName(), getSaveFileName(), getExistingDirectory()
 */
 QStringList QFileDialog::getOpenFileNames(QWidget *parent,
                                           const QString &caption,
@@ -1717,54 +1715,54 @@ QStringList QFileDialog::getOpenFileNames(QWidget *parent,
 }
 
 /*!
-  This is a convenience static function that will return a file name
-  selected by the user. The file does not have to exist.
+    This is a convenience static function that will return a file name selected
+    by the user. The file does not have to exist.
 
-  It creates a modal file dialog with the given \a parent widget. If the
-  parent is not 0, the dialog will be shown centered over the parent
-  widget.
+    It creates a modal file dialog with the given \a parent widget. If
+    \a parent is not 0, the dialog will be shown centered over the parent
+    widget.
 
-  \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 11
+    \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 11
 
-  The file dialog's working directory will be set to \a dir. If \a
-  dir includes a file name, the file will be selected. Only files that
-  match the \a filter are shown. The filter selected is set to
-  \a selectedFilter. The parameters \a dir, \a selectedFilter, and
-  \a filter may be empty strings. Multiple filters are separated with ';;'.
-  For instance:
+    The file dialog's working directory will be set to \a dir. If \a dir
+    includes a file name, the file will be selected. Only files that match the
+    \a filter are shown. The filter selected is set to \a selectedFilter. The
+    parameters \a dir, \a selectedFilter, and \a filter may be empty strings.
+    Multiple filters are separated with ';;'. For instance:
 
-  \code
+    \code
     "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
-  \endcode
+    \endcode
 
-  The \a options argument holds various
-  options about how to run the dialog, see the QFileDialog::Option enum for
-  more information on the flags you can pass.
+    The \a options argument holds various options about how to run the dialog,
+    see the QFileDialog::Option enum for more information on the flags you can
+    pass.
 
-  The default filter can be chosen by setting \a selectedFilter to the desired value.
+    The default filter can be chosen by setting \a selectedFilter to the
+    desired value.
 
-  The dialog's caption is set to \a caption. If \a caption is not
-  specified then a default caption will be used.
+    The dialog's caption is set to \a caption. If \a caption is not specified,
+    a default caption will be used.
 
-  Under Windows and Mac OS X, this static function will use the native
-  file dialog and not a QFileDialog.
+    On Windows and Mac OS X, this static function will use the native file
+    dialog and not a QFileDialog.
 
-  Note that on Windows the dialog will spin a blocking modal event loop
-  that will not dispatch any QTimers, and if parent is not 0 then it will
-  position the dialog just under the parent's title bar.
-  On Mac OS X, the filter argument is ignored.
+    On Windows the dialog will spin a blocking modal event loop that will not
+    dispatch any QTimers, and if \a parent is not 0 then it will position the
+    dialog just below the parent's title bar. On Mac OS X, with its native file
+    dialog, the filter argument is ignored.
 
-  Under Unix/X11, the normal behavior of the file dialog is to resolve
-  and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
-  \c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
-  entering \c{/usr/tmp}. If \a options includes DontResolveSymlinks,
-  the file dialog will treat symlinks as regular directories.
+    On Unix/X11, the normal behavior of the file dialog is to resolve and
+    follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
+    the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If
+    \a options includes DontResolveSymlinks the file dialog will treat symlinks
+    as regular directories.
 
-  \warning Do not delete \a parent during the execution of the dialog.
-           If you want to do this, you should create the dialog
-           yourself using one of the QFileDialog constructors.
+    \warning Do not delete \a parent during the execution of the dialog. If you
+    want to do this, you should create the dialog yourself using one of the
+    QFileDialog constructors.
 
-  \sa getOpenFileName(), getOpenFileNames(), getExistingDirectory()
+    \sa getOpenFileName(), getOpenFileNames(), getExistingDirectory()
 */
 QString QFileDialog::getSaveFileName(QWidget *parent,
                                      const QString &caption,
@@ -1810,46 +1808,43 @@ QString QFileDialog::getSaveFileName(QWidget *parent,
 }
 
 /*!
-  This is a convenience static function that will return an existing
-  directory selected by the user.
+    This is a convenience static function that will return an existing
+    directory selected by the user.
 
-  \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 12
+    \snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 12
 
-  This function creates a modal file dialog with the given \a parent
-  widget. If the parent is not 0, the dialog will be shown centered over
-  the parent widget.
+    This function creates a modal file dialog with the given \a parent widget.
+    If \a parent is not 0, the dialog will be shown centered over the parent
+    widget.
 
-  The dialog's working directory is set to \a dir, and the caption is
-  set to \a caption. Either of these may be an empty string in which case
-  the current directory and a default caption will be used
-  respectively.
+    The dialog's working directory is set to \a dir, and the caption is set to
+    \a caption. Either of these may be an empty string in which case the
+    current directory and a default caption will be used respectively.
 
-  The \a options argument holds various
-  options about how to run the dialog, see the QFileDialog::Option enum for
-  more information on the flags you can pass. Note that \l{QFileDialog::}{ShowDirsOnly}
-  must be set to ensure a native file dialog.
+    The \a options argument holds various options about how to run the dialog,
+    see the QFileDialog::Option enum for more information on the flags you can
+    pass. To ensure a native file dialog, \l{QFileDialog::}{ShowDirsOnly} must
+    be set.
 
-  Under Windows and Mac OS X, this static function will use the native
-  file dialog and not a QFileDialog. On Mac OS X, the \a dir argument
-  is ignored, the native dialog always displays the last visited directory.
-  On Windows CE, if the device has no native file dialog, a QFileDialog
-  will be used.
+    On Windows and Mac OS X, this static function will use the native file
+    dialog and not a QFileDialog. On Windows CE, if the device has no native
+    file dialog, a QFileDialog will be used.
 
-  Under Unix/X11, the normal behavior of the file dialog is to resolve
-  and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
-  \c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
-  entering \c{/usr/tmp}. If \a options includes DontResolveSymlinks,
-  the file dialog will treat symlinks as regular directories.
+    On Unix/X11, the normal behavior of the file dialog is to resolve and
+    follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
+    the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If
+    \a options includes DontResolveSymlinks, the file dialog will treat
+    symlinks as regular directories.
 
-  Note that on Windows the dialog will spin a blocking modal event loop
-  that will not dispatch any QTimers, and if parent is not 0 then it will
-  position the dialog just under the parent's title bar.
+    On Windows the dialog will spin a blocking modal event loop that will not
+    dispatch any QTimers, and if \a parent is not 0 then it will position the
+    dialog just below the parent's title bar.
 
-  \warning Do not delete \a parent during the execution of the dialog.
-           If you want to do this, you should create the dialog
-           yourself using one of the QFileDialog constructors.
+    \warning Do not delete \a parent during the execution of the dialog. If you
+    want to do this, you should create the dialog yourself using one of the
+    QFileDialog constructors.
 
-  \sa getOpenFileName(), getOpenFileNames(), getSaveFileName()
+    \sa getOpenFileName(), getOpenFileNames(), getSaveFileName()
 */
 QString QFileDialog::getExistingDirectory(QWidget *parent,
                                           const QString &caption,