From b20779b192eb7cf0033fef7c7062ab36b7ec011a Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Thu, 29 Oct 2020 18:05:25 +0100 Subject: [PATCH] Doc: Add a workaround for QUtf8StringView's missing docs QUtf8StringView is a specialization of QBasicUtf8StringView but we only want to document the former. Add a workaround when Q_CLANG_QDOC is defined to rename the base type, so the documentation in the .qdoc file is matched correctly. Fixes: QTBUG-88030 Task-number: QTBUG-86295 Change-Id: Id6e3d6fd5c28603bebf30771b7a47c3f76ca709d Reviewed-by: Paul Wicking --- src/corelib/text/qutf8stringview.h | 15 ++++- src/corelib/text/qutf8stringview.qdoc | 82 ++++++++++++--------------- 2 files changed, 50 insertions(+), 47 deletions(-) diff --git a/src/corelib/text/qutf8stringview.h b/src/corelib/text/qutf8stringview.h index 55621588bd..8e0656660d 100644 --- a/src/corelib/text/qutf8stringview.h +++ b/src/corelib/text/qutf8stringview.h @@ -117,14 +117,22 @@ struct wrap_char { using type = char; }; } // namespace QtPrivate +#ifdef Q_CLANG_QDOC +#define QBasicUtf8StringView QUtf8StringView +#else template +#endif class QBasicUtf8StringView { public: +#ifndef Q_CLANG_QDOC using storage_type = typename std::conditional::type::type; +#else + using storage_type = typename QtPrivate::hide_char8_t; +#endif typedef const storage_type value_type; typedef qptrdiff difference_type; typedef qsizetype size_type; @@ -226,7 +234,7 @@ public: [[nodiscard]] constexpr qsizetype size() const noexcept { return m_size; } [[nodiscard]] const_pointer data() const noexcept { return reinterpret_cast(m_data); } -#ifdef __cpp_char8_t +#if defined(__cpp_char8_t) || defined(Q_CLANG_QDOC) [[nodiscard]] const char8_t *utf8() const noexcept { return reinterpret_cast(m_data); } #endif @@ -344,6 +352,10 @@ private: const storage_type *m_data; qsizetype m_size; }; + +#ifdef Q_CLANG_QDOC +#undef QBasicUtf8StringView +#else template Q_DECLARE_TYPEINFO_BODY(QBasicUtf8StringView, Q_PRIMITIVE_TYPE); @@ -354,6 +366,7 @@ QT_END_NO_CHAR8_T_NAMESPACE QT_BEGIN_HAS_CHAR8_T_NAMESPACE using QUtf8StringView = QBasicUtf8StringView; QT_END_HAS_CHAR8_T_NAMESPACE +#endif // Q_CLANG_QDOC template , bool> = true> [[nodiscard]] inline q_no_char8_t::QUtf8StringView qToUtf8StringViewIgnoringNull(const QStringLike &s) noexcept diff --git a/src/corelib/text/qutf8stringview.qdoc b/src/corelib/text/qutf8stringview.qdoc index a5f05a8fb4..8ff208ff23 100644 --- a/src/corelib/text/qutf8stringview.qdoc +++ b/src/corelib/text/qutf8stringview.qdoc @@ -325,22 +325,22 @@ \a string must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \a str + This constructor only participates in overload resolution if \a string is an actual array and if \c Char is a compatible character type. The compatible character types are: \c char8_t, \c char, \c{signed char} and \c{unsigned char}. - \sa fromArray + \sa fromArray() */ /*! - \fn template QUtf8StringView::QUtf8StringView(const StdBasicString &str) + \fn template > QUtf8StringView::QUtf8StringView(const Container &str) Constructs a string view on \a str. The length is taken from \c{str.size()}. \c{str.data()} must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \c StdBasicString is an + This constructor only participates in overload resolution if \c Container is an instantiation of \c std::basic_string with a compatible character type. The compatible character types are: \c char8_t, \c char, \c{signed char} and \c{unsigned char}. @@ -353,7 +353,7 @@ */ /*! - \fn template static QBasicUtf8StringView fromArray(const Char (&string)[Size]) + \fn template > QUtf8StringView::fromArray(const Char (&string)[Size]) Constructs a string view on the full character string literal \a string, including any trailing \c{Char(0)}. If you don't want the @@ -587,48 +587,48 @@ */ /*! - \fn QUtf8StringView::mid(qsizetype start, qsizetype length) const + \fn QUtf8StringView::mid(qsizetype pos, qsizetype n) const - Returns the substring of length \a length starting at position - \a start in this object. + Returns the substring of length \a n starting at position + \a pos in this object. \obsolete Use sliced() instead in new code. - Returns an empty string view if \a start exceeds the - length of the string. If there are less than \a length code points - available in the string starting at \a start, or if - \a length is negative (default), the function returns all code points that - are available from \a start. + Returns an empty string view if \a n exceeds the + length of the string. If there are less than \a n code points + available in the string starting at \a pos, or if + \a n is negative (default), the function returns all code points that + are available from \a pos. \sa first(), last(), sliced(), chopped(), chop(), truncate() */ /*! - \fn QUtf8StringView::left(qsizetype length) const + \fn QUtf8StringView::left(qsizetype n) const \obsolete Use first() instead in new code. - Returns the substring of length \a length starting at position + Returns the substring of length \a n starting at position 0 in this object. - The entire string is returned if \a length is greater than or equal + The entire string is returned if \a n is greater than or equal to size(), or less than zero. - \sa first(), last(), sliced(), startsWith(), chopped(), chop(), truncate() + \sa first(), last(), sliced(), chopped(), chop(), truncate() */ /*! - \fn QUtf8StringView::right(qsizetype length) const + \fn QUtf8StringView::right(qsizetype n) const \obsolete Use last() instead in new code. - Returns the substring of length \a length starting at position - size() - \a length in this object. + Returns the substring of length \a n starting at position + size() - \a n in this object. - The entire string is returned if \a length is greater than or equal + The entire string is returned if \a n is greater than or equal to size(), or less than zero. - \sa first(), last(), sliced(), endsWith(), chopped(), chop(), truncate() + \sa first(), last(), sliced(), chopped(), chop(), truncate() */ /*! @@ -639,7 +639,7 @@ \note The behavior is undefined when \a n < 0 or \a n > size(). - \sa last(), sliced(), startsWith(), chopped(), chop(), truncate() + \sa last(), sliced(), chopped(), chop(), truncate() */ /*! @@ -649,7 +649,7 @@ \note The behavior is undefined when \a n < 0 or \a n > size(). - \sa first(), sliced(), endsWith(), chopped(), chop(), truncate() + \sa first(), sliced(), chopped(), chop(), truncate() */ /*! @@ -676,52 +676,42 @@ */ /*! - \fn QUtf8StringView::chopped(qsizetype length) const + \fn QUtf8StringView::chopped(qsizetype n) const - Returns the substring of length size() - \a length starting at the + Returns the substring of length size() - \a n starting at the beginning of this object. - Same as \c{first(size() - length)}. + Same as \c{first(size() - n)}. - \note The behavior is undefined when \a length < 0 or \a length > size(). + \note The behavior is undefined when \a n < 0 or \a n > size(). \sa sliced(), first(), last(), chop(), truncate() */ /*! - \fn QUtf8StringView::truncate(qsizetype length) + \fn QUtf8StringView::truncate(qsizetype n) - Truncates this string view to \a length code points. + Truncates this string view to \a n code points. - Same as \c{*this = first(length)}. + Same as \c{*this = first(n)}. - \note The behavior is undefined when \a length < 0 or \a length > size(). + \note The behavior is undefined when \a n < 0 or \a n > size(). \sa sliced(), first(), last(), chopped(), chop() */ /*! - \fn QUtf8StringView::chop(qsizetype length) + \fn QUtf8StringView::chop(qsizetype n) - Truncates this string view by \a length code points. + Truncates this string view by \a n code points. - Same as \c{*this = first(size() - length)}. + Same as \c{*this = first(size() - n)}. - \note The behavior is undefined when \a length < 0 or \a length > size(). + \note The behavior is undefined when \a n < 0 or \a n > size(). \sa sliced(), first(), last(), chopped(), truncate() */ -/*! - \fn QUtf8StringView::trimmed() const - - Strips leading and trailing whitespace and returns the result. - - Whitespace means any code point for which QChar::isSpace() returns - \c true. This includes the ASCII characters '\\t', '\\n', '\\v', - '\\f', '\\r', and ' '. -*/ - /*! \fn template qToUtf8StringViewIgnoringNull(const QStringLike &s); \relates QUtf8StringView