QDirListing: add some more API docs

Drive-by change: check the return value of QFile::open() to avoid a
compiler warning about [[nodiscard]], and to show users recommended
practices.

Change-Id: Iba55962c8beb008e63ad9da42e611371e7f8a6e1
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit 834ff5f996aa6f93180e898db13c146a24e1f85a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/doc/snippets/code/src_corelib_io_qdirlisting.cpp

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
 #include <QDirListing>
+#include <QFile>
 
 using namespace Qt::StringLiterals;
 
@@ -22,13 +23,12 @@ for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) {
 
 {
 //! [1]
-using ItFlag = QDirListing::IteratorFlag;
+using F = QDirListing::IteratorFlag;
-QDirListing dirList(u"/sys"_s, QStringList{u"scaling_cur_freq"_s},
+QDirListing dirList(u"/sys"_s, QStringList{u"scaling_cur_freq"_s}, F::FilesOnly | F::Recursive);
-                    QDir::NoFilter, ItFlag::Recursive);
 for (const auto &dirEntry : dirList) {
     QFile f(dirEntry.filePath());
-    f.open(QIODevice::ReadOnly);
+    if (f.open(QIODevice::ReadOnly))
-    qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
+        qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
 }
 //! [1]
 }
@@ -68,4 +68,22 @@ for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) {
 //! [4]
 }
 
+{
+//! [5]
+using F = QDirListing::IteratorFlag;
+const auto flags = F::FilesOnly | F::Recursive;
+for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
+    // ...
+}
+//! [5]
+}
+
+{
+//! [6]
+using F = QDirListing::IteratorFlag;
+const auto flags = F::FilesOnly | F::Recursive | F::ResolveSymlinks;
+for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
+    // ...
+}
+//! [6]
 }

src/corelib/io/qdirlisting.cpp

@@ -20,10 +20,17 @@
 
     \snippet code/src_corelib_io_qdirlisting.cpp 0
 
-    Here's how to find and read all files filtered by name, recursively:
+    Here's how to find and read all regular files filtered by name, recursively:
 
     \snippet code/src_corelib_io_qdirlisting.cpp 1
 
+    Here's how to list only regular files, recursively:
+    \snippet code/src_corelib_io_qdirlisting.cpp 5
+
+    Here's how to list only regular files and symbolic links to regular
+    files, recursively:
+    \snippet code/src_corelib_io_qdirlisting.cpp 6
+
     Iterators constructed by QDirListing (QDirListing::const_iterator) are
     forward-only, single-pass iterators, that don't allow random access. They
     can be used in ranged-for loops (or with STL alogrithms that don't