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 <paul.wicking@qt.io>

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 <bool UseChar8T>
+#endif
 class QBasicUtf8StringView
 {
 public:
+#ifndef Q_CLANG_QDOC
     using storage_type = typename std::conditional<UseChar8T,
             QtPrivate::hide_char8_t,
             QtPrivate::wrap_char
         >::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<const_pointer>(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<const char8_t*>(m_data); }
 #endif
 
@@ -344,6 +352,10 @@ private:
     const storage_type *m_data;
     qsizetype m_size;
 };
+
+#ifdef Q_CLANG_QDOC
+#undef QBasicUtf8StringView
+#else
 template <bool UseChar8T>
 Q_DECLARE_TYPEINFO_BODY(QBasicUtf8StringView<UseChar8T>, Q_PRIMITIVE_TYPE);
 
@@ -354,6 +366,7 @@ QT_END_NO_CHAR8_T_NAMESPACE
 QT_BEGIN_HAS_CHAR8_T_NAMESPACE
 using QUtf8StringView = QBasicUtf8StringView<true>;
 QT_END_HAS_CHAR8_T_NAMESPACE
+#endif // Q_CLANG_QDOC
 
 template <typename QStringLike, std::enable_if_t<std::is_same_v<QStringLike, QByteArray>, 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 <typename StdBasicString> QUtf8StringView::QUtf8StringView(const StdBasicString &str)
+    \fn template <typename Container, if_compatible_container<Container>> 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 <typename Char, size_t Size> static QBasicUtf8StringView fromArray(const Char (&string)[Size])
+    \fn template <typename Char, size_t Size, if_compatible_char<Char>> 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,53 +676,43 @@
 */
 
 /*!
-    \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 <typename QStringLike> qToUtf8StringViewIgnoringNull(const QStringLike &s);
     \relates QUtf8StringView
     \internal