From 756104d5e140bfb585a2762de757ef2204db9bf4 Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Fri, 25 Sep 2020 15:24:58 +0200 Subject: [PATCH] Fix some qdoc warnings for QString/View/Tokenizer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use correct member function prototype, which requires the template declaration. Remove see-alsos that don't exist. Document parameters for qTokenize. Still lots of warnings from QStringTokenizer, due to the inheritance structure of that template class and the declarations of nested types in undocumented base classes. Also, qdoc doesn't seem to recognize training this-lvalue/this-rvalue declarations for overloads, and considers the second toContainer documentations to override the first. Change-Id: Iadf967d3328ddda52b6f66786836853bddeda79b Reviewed-by: Topi Reiniö --- src/corelib/text/qstring.cpp | 4 +- src/corelib/text/qstringtokenizer.cpp | 79 ++++++++++++++++----------- src/corelib/text/qstringtokenizer.h | 8 +++ src/corelib/text/qstringview.cpp | 10 ++-- 4 files changed, 62 insertions(+), 39 deletions(-) diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp index b05a3cd707..349d4e1e2e 100644 --- a/src/corelib/text/qstring.cpp +++ b/src/corelib/text/qstring.cpp @@ -2387,7 +2387,7 @@ QString::QString(QChar ch) \snippet qstring/main.cpp 45 If you want to append a certain number of identical characters to - the string, use the \l {QString::}{resize(int, QChar)} overload. + the string, use the \l {QString::}{resize(qsizetype, QChar)} overload. If you want to expand the string so that it reaches a certain width and fill the new positions with a particular character, use @@ -2417,7 +2417,7 @@ void QString::resize(qsizetype size) \overload \since 5.7 - Unlike \l {QString::}{resize(int)}, this overload + Unlike \l {QString::}{resize(qsizetype)}, this overload initializes the new characters to \a fillChar: \snippet qstring/main.cpp 46 diff --git a/src/corelib/text/qstringtokenizer.cpp b/src/corelib/text/qstringtokenizer.cpp index 4e8ffc2c8e..066ef25a83 100644 --- a/src/corelib/text/qstringtokenizer.cpp +++ b/src/corelib/text/qstringtokenizer.cpp @@ -143,30 +143,30 @@ QT_BEGIN_NAMESPACE use(e); \endcode - \sa QStringView::split(), QLatin1String::split(), QRegularExpression + \sa QStringView::split(), QString::split(), QRegularExpression */ /*! - \typedef QStringTokenizer::value_type + \typedef template QStringTokenizer::value_type Alias for \c{const QStringView} or \c{const QLatin1String}, depending on the tokenizer's \c Haystack template argument. */ /*! - \typedef QStringTokenizer::difference_type + \typedef template QStringTokenizer::difference_type Alias for qsizetype. */ /*! - \typedef QStringTokenizer::size_type + \typedef template QStringTokenizer::size_type Alias for qsizetype. */ /*! - \typedef QStringTokenizer::reference + \typedef template QStringTokenizer::reference Alias for \c{value_type &}. @@ -175,13 +175,13 @@ QT_BEGIN_NAMESPACE */ /*! - \typedef QStringTokenizer::const_reference + \typedef template QStringTokenizer::const_reference Alias for \c{value_type &}. */ /*! - \typedef QStringTokenizer::pointer + \typedef template QStringTokenizer::pointer Alias for \c{value_type *}. @@ -190,13 +190,13 @@ QT_BEGIN_NAMESPACE */ /*! - \typedef QStringTokenizer::const_pointer + \typedef template QStringTokenizer::const_pointer Alias for \c{value_type *}. */ /*! - \typedef QStringTokenizer::iterator + \typedef template QStringTokenizer::iterator This typedef provides an STL-style const iterator for QStringTokenizer. @@ -208,7 +208,7 @@ QT_BEGIN_NAMESPACE */ /*! - \typedef QStringTokenizer::const_iterator + \typedef template QStringTokenizer::const_iterator This typedef provides an STL-style const iterator for QStringTokenizer. @@ -217,7 +217,7 @@ QT_BEGIN_NAMESPACE */ /*! - \typedef QStringTokenizer::sentinel + \typedef template QStringTokenizer::sentinel This typedef provides an STL-style sentinel for QStringTokenizer::iterator and QStringTokenizer::const_iterator. @@ -226,8 +226,8 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QStringTokenizer(Haystack haystack, String needle, Qt::CaseSensitivity cs, Qt::SplitBehavior sb) - \fn QStringTokenizer(Haystack haystack, String needle, Qt::SplitBehavior sb, Qt::CaseSensitivity cs) + \fn template QStringTokenizer::QStringTokenizer(Haystack haystack, Needle needle, Qt::CaseSensitivity cs, Qt::SplitBehavior sb) + \fn template QStringTokenizer::QStringTokenizer(Haystack haystack, Needle needle, Qt::SplitBehavior sb, Qt::CaseSensitivity cs) Constructs a string tokenizer that splits the string \a haystack into substrings wherever \a needle occurs, and allows iteration @@ -241,11 +241,11 @@ QT_BEGIN_NAMESPACE If \a sb is QString::SkipEmptyParts, empty entries don't appear in the result. By default, empty entries are included. - \sa QStringView::split(), QLatin1String::split(), Qt::CaseSensitivity, Qt::SplitBehavior + \sa QStringView::split(), QString::split(), Qt::CaseSensitivity, Qt::SplitBehavior */ /*! - \fn QStringTokenizer::const_iterator QStringTokenizer::begin() const + \fn template QStringTokenizer::const_iterator QStringTokenizer::begin() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first token in the list. @@ -254,7 +254,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QStringTokenizer::const_iterator QStringTokenizer::cbegin() const + \fn template QStringTokenizer::const_iterator QStringTokenizer::cbegin() const Same as begin(). @@ -262,7 +262,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QStringTokenizer::sentinel QStringTokenizer::end() const + \fn template QStringTokenizer::sentinel QStringTokenizer::end() const Returns a const \l{STL-style iterators}{STL-style sentinel} pointing to the imaginary token after the last token in the list. @@ -271,7 +271,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QStringTokenizer::sentinel QStringTokenizer::cend() const + \fn template QStringTokenizer::sentinel QStringTokenizer::cend() const Same as end(). @@ -279,19 +279,18 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QStringTokenizer::toContainer(Container &&c) const & + \fn template template Container QStringTokenizer::toContainer(Container &&c) const & - Convenience method to convert the lazy sequence into a - (typically) random-access container. + Converts the lazy sequence into a (typically) random-access container of + type \c Container. This function is only available if \c Container has a \c value_type matching this tokenizer's value_type. - If you pass in a named container (an lvalue), then that container - is filled, and a reference to it is returned. - - If you pass in a temporary container (an rvalue, incl. the default - argument), then that container is filled, and returned by value. + If you pass in a named container (an lvalue)for \a c, then that container + is filled, and a reference to it is returned. If you pass in a temporary + container (an rvalue, incl. the default argument), then that container is + filled, and returned by value. \code // assuming tok's value_type is QStringView, then... @@ -311,9 +310,12 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QStringTokenizer::toContainer(Container &&c) const && + \fn template template Container QStringTokenizer::toContainer(Container &&c) const && \overload + Converts the lazy sequence into a (typically) random-access container of + type \c Container. + In addition to the constraints on the lvalue-this overload, this rvalue-this overload is only available when this QStringTokenizer does not store the haystack internally, as this could create a @@ -341,17 +343,30 @@ QT_BEGIN_NAMESPACE func(QStringTokenizer{QStringView{widget.text()}, u','}.toContainer()); // OK: compiler keeps widget.text() around until after func() has executed \endcode + + If you pass in a named container (an lvalue)for \a c, then that container + is filled, and a reference to it is returned. If you pass in a temporary + container (an rvalue, incl. the default argument), then that container is + filled, and returned by value. */ /*! - \fn qTokenize(Haystack &&haystack, Needle &&needle, Flags...flags) + \fn template auto qTokenize(Haystack &&haystack, Needle &&needle, Flags...flags) \relates QStringTokenizer \since 6.0 - Factory function for QStringTokenizer. You can use this function - if your compiler doesn't, yet, support C++17 Class Template - Argument Deduction (CTAD), but we recommend direct use of - QStringTokenizer with CTAD instead. + Factory function for a QStringTokenizer that splits the string \a haystack + into substrings wherever \a needle occurs, and allows iteration + over those strings as they are found. If \a needle does not match + anywhere in \a haystack, a single element containing \a haystack + is produced. + + Pass values from Qt::CaseSensitivity and Qt::SplitBehavior enumerators + as \a flags to modify the behavior of the tokenizer. + + You can use this function if your compiler doesn't, yet, support C++17 Class + Template Argument Deduction (CTAD). We recommend direct use of QStringTokenizer + with CTAD instead. */ QT_END_NAMESPACE diff --git a/src/corelib/text/qstringtokenizer.h b/src/corelib/text/qstringtokenizer.h index 47ee51bfa6..b4272ec069 100644 --- a/src/corelib/text/qstringtokenizer.h +++ b/src/corelib/text/qstringtokenizer.h @@ -328,7 +328,11 @@ public: this->needleView(needle), sb, cs} {} +#ifdef Q_QDOC + template +#else template, if_compatible_container = true> +#endif Container toContainer(Container &&c = {}) const & { for (auto e : *this) @@ -336,8 +340,12 @@ public: return c; } +#ifdef Q_QDOC + template +#else template, if_compatible_container = true, if_haystack_not_pinned = true> +#endif Container toContainer(Container &&c = {}) const && { for (auto e : *this) diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp index aeec699f7f..35456cce77 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -1227,11 +1227,11 @@ QT_BEGIN_NAMESPACE /*! - \fn QStringView::tokenize(Needle &&sep, Flags...flags) const - \fn QLatin1String::tokenize(Needle &&sep, Flags...flags) const - \fn QString::tokenize(Needle &&sep, Flags...flags) const & - \fn QString::tokenize(Needle &&sep, Flags...flags) const && - \fn QString::tokenize(Needle &&sep, Flags...flags) && + \fn template auto QStringView::tokenize(Needle &&sep, Flags...flags) const + \fn template auto QLatin1String::tokenize(Needle &&sep, Flags...flags) const + \fn template auto QString::tokenize(Needle &&sep, Flags...flags) const & + \fn template auto QString::tokenize(Needle &&sep, Flags...flags) const && + \fn template auto QString::tokenize(Needle &&sep, Flags...flags) && Splits the string into substring views wherever \a sep occurs, and returns a lazy sequence of those strings.