From e960afffc9d9b5603a6304a530bb529c52d8fbad Mon Sep 17 00:00:00 2001 From: Ahmad Samir Date: Tue, 3 Sep 2024 17:56:17 +0300 Subject: [PATCH] QDirListing: flesh out API docs - Let qdoc generate docs for const_iterator/sentinel - Document pre- and post-increment operators - Document const_iterators typedefs - DRY API docs Change-Id: Ia559541118586ca0314cd5f618acda3f7c820659 Reviewed-by: Marc Mutz (cherry picked from commit 68a06e99a8577d08e8b885f0b417b1c9f90a7459) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/io/qdirlisting.cpp | 106 ++++++++++++++++++++++++++------- 1 file changed, 86 insertions(+), 20 deletions(-) diff --git a/src/corelib/io/qdirlisting.cpp b/src/corelib/io/qdirlisting.cpp index 6b9741a472b..501f00dc86c 100644 --- a/src/corelib/io/qdirlisting.cpp +++ b/src/corelib/io/qdirlisting.cpp @@ -32,12 +32,13 @@ files, recursively: \snippet code/src_corelib_io_qdirlisting.cpp 6 - Iterators constructed by QDirListing (QDirListing::const_iterator) - model C++20 +//! [std-input-iterator-tag] + QDirListing::const_iterator models C++20 \l{https://en.cppreference.com/w/cpp/iterator/input_iterator}{std::input_iterator}, - that is, they are move-only, - forward-only, single-pass iterators, that don't allow random access. They - can be used in ranged-for loops (or with C++20 range algorithms that don't + that is, it is a move-only, forward-only, single-pass iterator, that + doesn't allow random access. +//! [std-input-iterator-tag] + It can be used in ranged-for loops (or with C++20 range algorithms that don't require random access iterators). Dereferencing a valid iterator returns a QDirListing::DirEntry object. The (c)end() sentinel marks the end of the iteration. Dereferencing an iterator that is equal to \l{sentinel} is @@ -661,6 +662,62 @@ QStringList QDirListing::nameFilters() const return d->nameFilters; } +/*! + \class QDirListing::const_iterator + \since 6.8 + \inmodule QtCore + \ingroup io + + The iterator type returned by QDirListing::cbegin(). + +//! [dirlisting-iterator-behavior] + \list + \li This is a forward-only, single-pass iterator (you cannot iterate + directory entries in reverse order) + \li Can't be copied, only \c{std::move()}d. + \li \include qdirlisting.cpp post-increment-partially-formed + \li Doesn't allow random access + \li Can be used in ranged-for loops; or with C++20 std::ranges algorithms + that don't require random access iterators + \li Dereferencing a valid iterator returns a \c{const DirEntry &} + \li (c)end() returns a \l QDirListing::sentinel that signals the end of + the iteration. Dereferencing an iterator that compares equal to end() + is undefined behavior + \endlist +//! [dirlisting-iterator-behavior] + + \include qdirlisting.cpp ranges-algorithms-note + + \sa QDirListing, QDirListing::sentinel, QDirListing::DirEntry +*/ + +/*! + \typealias QDirListing::const_iterator::reference + + A typedef for \c {const QDirListing::DirEntry &}. +*/ + +/*! + \typealias QDirListing::const_iterator::pointer + + A typedef for \c {const QDirListing::DirEntry *}. +*/ + +/*! + \class QDirListing::sentinel + \since 6.8 + \inmodule QtCore + \ingroup io + + \l QDirListing returns an object of this type to signal the end of + iteration. Dereferencing a \l QDirListing::const_iterator that is + equal to \c sentinel{} is undefined behavior. + + \include qdirlisting.cpp ranges-algorithms-note + + \sa QDirListing, QDirListing::const_iterator, QDirListing::DirEntry +*/ + /*! \fn QDirListing::const_iterator QDirListing::begin() const \fn QDirListing::const_iterator QDirListing::cbegin() const @@ -670,20 +727,10 @@ QStringList QDirListing::nameFilters() const (c)begin() returns a QDirListing::const_iterator that can be used to iterate over directory entries. - \list - \li This is a forward-only, single-pass iterator (you cannot iterate - directory entries in reverse order) - \li Can't be copied, only \c{std::move()}d. - \li Doesn't allow random access - \li Can be used in ranged-for loops; or with STL algorithms that don't - require random access iterators - \li Dereferencing a valid iterator returns a \c{const DirEntry &} - \li (c)end() returns a sentinel that signals the end of the iteration. - Dereferencing an iterator that compares equal to end() is undefined - behavior - \li Each time (c)begin() is called on the same QDirListing object, - the internal state is reset and the iteration starts anew - \endlist + \include qdirlisting.cpp dirlisting-iterator-behavior + + \note Each time (c)begin() is called on the same QDirListing object, + the internal state is reset and the iteration starts anew. (Some of the above restrictions are dictated by the underlying system library functions' implementation). @@ -694,9 +741,11 @@ QStringList QDirListing::nameFilters() const Here's how to find and read all files filtered by name, recursively: \snippet code/src_corelib_io_qdirlisting.cpp 1 +//! [ranges-algorithms-note] \note The "classical" STL algorithms don't support iterator/sentinel, so - you need to use C++20 std::ranges algorithms fo QDirListing, or else a + you need to use C++20 std::ranges algorithms for QDirListing, or else a 3rd-party library that provides range-based algorithms in C++17. +//! [ranges-algorithms-note] \sa QDirListing::DirEntry */ @@ -725,9 +774,26 @@ QDirListing::const_iterator QDirListing::begin() const /*! \fn QDirListing::const_iterator::operator++() + Pre-increment operator. Advances the iterator and returns a reference to it. */ +/*! + \fn void QDirListing::const_iterator::operator++(int) + + Post-increment operator. + + \include qdirlisting.cpp std-input-iterator-tag + +//! [post-increment-partially-formed] + The return value of post-increment on objects that model + \c std::input_iterator is partially-formed (a copy of an iterator that + has since been advanced), the only valid operations on such an object + are destruction and assignment of a new iterator. Therefore the + post-increment operator advances the iterator and returns \c void. +//! [post-increment-partially-formed] +*/ + /*! \internal