From 48758816db9983c2b51db486aacff0e51e91daac Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Thu, 22 Oct 2020 14:44:10 +0200 Subject: Fix documentation for QIterable and related classes Correctly specify template parameters, fix typos, add \fn where missing, explicitly specify scope in see-also references. Change-Id: I8b04a2b76033b206098e816d1d07d105b838c260 Reviewed-by: Ulf Hermann --- src/corelib/kernel/qiterable.cpp | 161 +++++++++++++++++++-------------------- 1 file changed, 80 insertions(+), 81 deletions(-) (limited to 'src/corelib/kernel/qiterable.cpp') diff --git a/src/corelib/kernel/qiterable.cpp b/src/corelib/kernel/qiterable.cpp index f397749e51..0001a2311a 100644 --- a/src/corelib/kernel/qiterable.cpp +++ b/src/corelib/kernel/qiterable.cpp @@ -49,56 +49,56 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QBaseIterator::QBaseIterator(const QIterable *iterable, void *iterator) + \fn template QBaseIterator::QBaseIterator(const QIterable *iterable, void *iterator) \internal Creates a const QBaseIterator from an \a iterable and an \a iterator. */ /*! - \fn QBaseIterator::QBaseIterator(QIterable *iterable, void *iterator) + \fn template QBaseIterator::QBaseIterator(QIterable *iterable, void *iterator) \internal Creates a non-const QBaseIterator from an \a iterable and an \a iterator. */ /*! - \fn QBaseIterator::QBaseIterator(QBaseIterator &&other) + \fn template QBaseIterator::QBaseIterator(QBaseIterator &&other) \internal Move-constructs a QBaseIterator from \a other, preserving its const-ness. */ /*! - \fn QBaseIterator::QBaseIterator(const QBaseIterator &other) + \fn template QBaseIterator::QBaseIterator(const QBaseIterator &other) \internal Copy-constructs a QBaseIterator from \a other, preserving its const-ness. */ /*! - \fn QBaseIterator::~QBaseIterator() + \fn template QBaseIterator::~QBaseIterator() \internal Destroys a QBaseIterator. */ /*! - \fn QBaseIterator &QBaseIterator::operator=(const QBaseIterator &other) + \fn template QBaseIterator &QBaseIterator::operator=(const QBaseIterator &other) \internal Copy-assigns a QBaseIterator from \a other, preserving its const-ness. */ /*! - \fn void QBaseIterator::initIterator(const void *copy) + \fn template void QBaseIterator::initIterator(const void *copy) \internal Initializes the internal native iterator by duplicating \a copy, if given. */ /*! - \fn void QBaseIterator::clearIterator() + \fn template void QBaseIterator::clearIterator() \internal Destroys the internal native iterator. @@ -106,14 +106,14 @@ QT_BEGIN_NAMESPACE /*! - \fn QMetaContainer QBaseIterator::metaContainer() const + \fn QMetaContainer QBaseIterator::metaContainer() const \internal Returns the meta sequence. */ /*! - \fn QIterable *QBaseIterator::mutableIterable() const + \fn template QIterable *QBaseIterator::mutableIterable() const \internal Returns a non-const pointer to the iterable, if the original iterable was @@ -121,36 +121,36 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QIterable *QBaseIterator::constIterable() const + \fn template const QIterable *QBaseIterator::constIterable() const \internal Returns a const pointer to the iterable. */ /*! - \fn void *QBaseIterator::mutableIterator() + \fn template void *QBaseIterator::mutableIterator() Returns a non-const pointer to the internal native iterator. */ /*! - \fn const void *QBaseIterator::constIterator() const + \fn template const void *QBaseIterator::constIterator() const Returns a const pointer to the internal native iterator. */ /*! - \fn QBaseIterator &QBaseIterator::operator=(QBaseIterator &&other) + \fn template QBaseIterator &QBaseIterator::operator=(QBaseIterator &&other) \internal Move-assigns a QBaseIterator from \a other, preserving its const-ness. */ /*! - \class Qiterator + \class QIterator \since 6.0 \inmodule QtCore - \brief The QIterator allows iteration over a container in a QVariant. + \brief The QIterator is a template class that allows iteration over a container in a QVariant. A QIterator can only be created by a QIterable instance, and can be used in a way similar to other stl-style iterators. Generally, QIterator should @@ -161,13 +161,13 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QIterator::QIterator(QIterable *iterable, void *iterator) + \fn template QIterator::QIterator(QIterable *iterable, void *iterator) Creates an iterator from an \a iterable and a pointer to a native \a iterator. */ /*! - \fn bool QIterator::operator==(const QIterator &other) const + \fn template bool QIterator::operator==(const QIterator &other) const Returns \c true if \a other points to the same item as this iterator; otherwise returns \c false. @@ -176,7 +176,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn bool QIterator::operator!=(const QIterator &other) const + \fn template bool QIterator::operator!=(const QIterator &other) const Returns \c true if \a other points to a different item than this iterator; otherwise returns \c false. @@ -185,7 +185,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QIterator &QIterator::operator++() + \fn template QIterator &QIterator::operator++() The prefix ++ operator (\c{++it}) advances the iterator to the next item in the container and returns an iterator to the new current @@ -197,7 +197,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QIterator QIterator::operator++(int) + \fn template QIterator QIterator::operator++(int) \overload The postfix ++ operator (\c{it++}) advances the iterator to the @@ -207,7 +207,7 @@ QT_BEGIN_NAMESPACE /*! - \fn QIterator &QIterator::operator--() + \fn template QIterator &QIterator::operator--() The prefix -- operator (\c{--it}) makes the preceding item current and returns an iterator to the new current item. @@ -217,11 +217,11 @@ QT_BEGIN_NAMESPACE If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa operator++(), canReverseIterate() + \sa operator++(), QIterable::canReverseIterate() */ /*! - \fn QIterator QIterator::operator--(int) + \fn template QIterator QIterator::operator--(int) \overload @@ -231,11 +231,11 @@ QT_BEGIN_NAMESPACE If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa canReverseIterate() + \sa QIterable::canReverseIterate() */ /*! - \fn QIterator &QIterator::operator+=(qsizetype j) + \fn template QIterator &QIterator::operator+=(qsizetype j) Advances the iterator by \a j items. @@ -243,18 +243,18 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QIterator &QIterator::operator-=(qsizetype j) + \fn template QIterator &QIterator::operator-=(qsizetype j) Makes the iterator go back by \a j items. If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa operator+=(), operator-(), canReverseIterate() + \sa operator+=(), operator-(), QIterable::canReverseIterate() */ /*! - \fn QIterator QIterator::operator+(qsizetype j) const + \fn template QIterator QIterator::operator+(qsizetype j) const Returns an iterator to the item at \a j positions forward from this iterator. @@ -263,7 +263,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QIterator QIterator::operator-(qsizetype j) const + \fn template QIterator QIterator::operator-(qsizetype j) const Returns an iterator to the item at \a j positions backward from this iterator. @@ -271,25 +271,25 @@ QT_BEGIN_NAMESPACE If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa operator+(), operator-=(), canReverseIterate() + \sa operator+(), operator-=(), QIterable::canReverseIterate() */ /*! - \fn qsizetype QIterator::operator-(const QIterator &j) const + \fn template qsizetype QIterator::operator-(const QIterator &j) const Returns the distance between the two iterators. - \sa operator+(), operator-=(), canReverseIterator() + \sa operator+(), operator-=(), QIterable::canReverseIterate() */ /*! - QConstIterator::QConstIterator(const QIterable *iterable, void *iterator) + \fn template QConstIterator::QConstIterator(const QIterable *iterable, void *iterator) Creates a QConstIterator to wrap \a iterator, operating on \a iterable. */ /*! - bool QConstIterator::operator==(const QConstIterator &other) const + \fn template bool QConstIterator::operator==(const QConstIterator &other) const Returns \c true if \a other points to the same item as this iterator; otherwise returns \c false. @@ -298,7 +298,7 @@ QT_BEGIN_NAMESPACE */ /*! - bool QConstIterator::operator!=(const QConstIterator &other) const + \fn template bool QConstIterator::operator!=(const QConstIterator &other) const Returns \c true if \a other points to a different item than this iterator; otherwise returns \c false. @@ -307,19 +307,19 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator &QConstIterator::operator++() + \fn template QConstIterator &QConstIterator::operator++() The prefix ++ operator (\c{++it}) advances the iterator to the next item in the container and returns an iterator to the new current item. - Calling this function on QIterable::end() leads to undefined results. + Calling this function on QIterable::end() leads to undefined results. \sa operator--() */ /*! - \fn QConstIterator QConstIterator::operator++(int) + \fn template QConstIterator QConstIterator::operator++(int) \overload @@ -329,12 +329,12 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator &QConstIterator::operator--() + \fn template QConstIterator &QConstIterator::operator--() The prefix -- operator (\c{--it}) makes the preceding item current and returns an iterator to the new current item. - Calling this function on QIterable::begin() leads to undefined results. + Calling this function on QIterable::begin() leads to undefined results. If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. @@ -343,7 +343,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator QConstIterator::operator--(int) + \fn template QConstIterator QConstIterator::operator--(int) \overload @@ -357,7 +357,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator &QConstIterator::operator+=(qsizetype j) + \fn template QConstIterator &QConstIterator::operator+=(qsizetype j) Advances the iterator by \a j items. @@ -365,7 +365,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator &QConstIterator::operator-=(qsizetype j) + \fn template QConstIterator &QConstIterator::operator-=(qsizetype j) Makes the iterator go back by \a j items. @@ -376,7 +376,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator QConstIterator::operator+(qsizetype j) const + \fn template QConstIterator QConstIterator::operator+(qsizetype j) const Returns an iterator to the item at \a j positions forward from this iterator. @@ -385,7 +385,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator QConstIterator::operator-(qsizetype j) const + \fn template QConstIterator QConstIterator::operator-(qsizetype j) const Returns an iterator to the item at \a j positions backward from this iterator. @@ -397,7 +397,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn qsizetype QConstIterator::operator-(const QConstIterator &j) const + \fn template qsizetype QConstIterator::operator-(const QConstIterator &j) const Returns the distance between the two iterators. @@ -407,12 +407,11 @@ QT_BEGIN_NAMESPACE /*! \class QIterable \since 6.0 - - QIterable is the base class for QSequentialIterable and QAssociativeIterable. + \brief QIterable is a template class that is the base class for QSequentialIterable and QAssociativeIterable. */ /*! - \fn bool QIterable::canInputIterate() const + \fn template bool QIterable::canInputIterate() const Returns whether the container has an input iterator. This corresponds to the std::input_iterator_tag iterator trait of the iterator and @@ -420,7 +419,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn bool QIterable::canForwardIterate() const + \fn template bool QIterable::canForwardIterate() const Returns whether it is possible to iterate over the container in forward direction. This corresponds to the std::forward_iterator_tag iterator trait @@ -428,7 +427,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn bool QIterable::canReverseIterate() const + \fn template bool QIterable::canReverseIterate() const Returns whether it is possible to iterate over the container in reverse. This corresponds to the std::bidirectional_iterator_tag iterator trait of the @@ -436,7 +435,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn bool QIterable::canRandomAccessIterate() const + \fn template bool QIterable::canRandomAccessIterate() const Returns whether it is possible to efficiently skip over multiple values using and iterator. This corresponds to the std::random_access_iterator_tag @@ -444,43 +443,43 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QConstIterator QIterable::constBegin() const + \fn template QConstIterator QIterable::constBegin() const Returns a QConstIterator for the beginning of the container. This can be used in stl-style iteration. - \sa end() + \sa constEnd(), mutableBegin() */ /*! - \fn QConstIterator QIterable::constEnd() const + \fn template QConstIterator QIterable::constEnd() const Returns a Qterable::QConstIterator for the end of the container. This can be used in stl-style iteration. - \sa begin() + \sa constBegin(), mutableEnd() */ /*! - \fn QIterator QIterable::mutableBegin() + \fn template QIterator QIterable::mutableBegin() Returns a QIterator for the beginning of the container. This can be used in stl-style iteration. - \sa end() + \sa mutableEnd(), constBegin() */ /*! - \fn QIterator QIterable::mutableEnd() + \fn template QIterator QIterable::mutableEnd() Returns a QSequentialIterable::iterator for the end of the container. This can be used in stl-style iteration. - \sa begin() + \sa mutableBegin(), constEnd() */ /*! - \fn qsizetype QIterable::size() const + \fn template qsizetype QIterable::size() const Returns the number of values in the container. */ @@ -489,7 +488,7 @@ QT_BEGIN_NAMESPACE \class QTaggedIterator \since 6.0 \inmodule QtCore - \brief Wraps an iterator and exposes standard iterator traits. + \brief QTaggedIterator is a template class that wraps an iterator and exposes standard iterator traits. In order to use an iterator any of the standard algorithms, it iterator traits need to be known. As QSequentialIterable can work with many different @@ -499,15 +498,15 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QTaggedIterator::StdIterator(Iterator &&it) + \fn template QTaggedIterator::QTaggedIterator(Iterator &&it) - Constructs a StdIterator from an iterator or QConstIterator \a it. Checks + Constructs a QTaggedIterator from an iterator or QConstIterator \a it. Checks whether the IteratorCategory passed as template argument matches the run time capabilities of \a it and refuses \a it if not. */ /*! - \fn bool QTaggedIterator::operator==(const StdIterator &other) const + \fn template bool QTaggedIterator::operator==(const QTaggedIterator &other) const Returns \c true if \a other points to the same item as this iterator; otherwise returns \c false. @@ -516,7 +515,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn bool QTaggedIterator::operator!=(const StdIterator &other) const + \fn template bool QTaggedIterator::operator!=(const QTaggedIterator &other) const Returns \c true if \a other points to a different item than this iterator; otherwise returns \c false. @@ -525,7 +524,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QTaggedIterator &QTaggedIterator::operator++() + \fn template QTaggedIterator &QTaggedIterator::operator++() The prefix ++ operator (\c{++it}) advances the iterator to the next item in the container and returns an iterator to the new current @@ -537,7 +536,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QTaggedIterator QTaggedIterator::operator++(int) + \fn template QTaggedIterator QTaggedIterator::operator++(int) \overload The postfix ++ operator (\c{it++}) advances the iterator to the @@ -547,7 +546,7 @@ QT_BEGIN_NAMESPACE /*! - \fn QTaggedIterator &QTaggedIterator::operator--() + \fn template QTaggedIterator &QTaggedIterator::operator--() The prefix -- operator (\c{--it}) makes the preceding item current and returns an iterator to the new current item. @@ -557,11 +556,11 @@ QT_BEGIN_NAMESPACE If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa operator++(), canReverseIterate() + \sa operator++(), QIterable::canReverseIterate() */ /*! - \fn QTaggedIterator QTaggedIterator::operator--(int) + \fn template QTaggedIterator QTaggedIterator::operator--(int) \overload The postfix -- operator (\c{it--}) makes the preceding item @@ -570,12 +569,12 @@ QT_BEGIN_NAMESPACE If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa canReverseIterate() + \sa QIterable::canReverseIterate() */ /*! - \fn QTaggedIterator &QTaggedIterator::operator+=(qsizetype j) + \fn template QTaggedIterator &QTaggedIterator::operator+=(qsizetype j) Advances the iterator by \a j items. @@ -583,18 +582,18 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QTaggedIterator &QTaggedIterator::operator-=(qsizetype j) + \fn template QTaggedIterator &QTaggedIterator::operator-=(qsizetype j) Makes the iterator go back by \a j items. If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa operator+=(), operator-(), canReverseIterate() + \sa operator+=(), operator-(), QIterable::canReverseIterate() */ /*! - \fn QTaggedIterator QTaggedIterator::operator+(qsizetype j) const + \fn template QTaggedIterator QTaggedIterator::operator+(qsizetype j) const Returns an iterator to the item at \a j positions forward from this iterator. @@ -603,7 +602,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QTaggedIterator QTaggedIterator::operator-(qsizetype j) const + \fn template QTaggedIterator QTaggedIterator::operator-(qsizetype j) const Returns an iterator to the item at \a j positions backward from this iterator. @@ -611,15 +610,15 @@ QT_BEGIN_NAMESPACE If the container in the QVariant does not support bi-directional iteration, calling this function leads to undefined results. - \sa operator+(), operator-=(), canReverseIterate() + \sa operator+(), operator-=(), QIterable::canReverseIterate() */ /*! - \fn qsizetype QTaggedIterator::operator-(const QTaggedIterator &j) const + \fn template qsizetype QTaggedIterator::operator-(const QTaggedIterator &j) const Returns the distance between the two iterators. - \sa operator+(), operator-=(), canReverseIterator() + \sa operator+(), operator-=(), QIterable::canReverseIterate() */ QT_END_NAMESPACE -- cgit v1.2.3