From 0afe31fa51a26d12be21c1b9c6e886abb9775441 Mon Sep 17 00:00:00 2001
From: Marc Mutz <marc.mutz@qt.io>
Date: Thu, 5 Dec 2024 12:27:39 +0100
Subject: [PATCH] QSpan: document slice() and chop()

Needed to use a weird combination of \c and \a here, as qdoc on
one hand insists that all parameters be documented, and OTOH doesn't
support \a within \c.

Writing anything else than the equivalent code in \c to appease qdoc
would be childish. Equivalent code is the best-possible documentation,
as it leaves no question unanswered.

Pick-to: 6.9
Task-number: QTBUG-131672
Change-Id: I512872360b7eb212001723f2ba12d4c6eac0b6b0
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
---
 src/corelib/tools/qspan.qdoc | 39 +++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/src/corelib/tools/qspan.qdoc b/src/corelib/tools/qspan.qdoc
index c8e5103f9eb..e70abef0f49 100644
--- a/src/corelib/tools/qspan.qdoc
+++ b/src/corelib/tools/qspan.qdoc
@@ -642,7 +642,7 @@
     These functions do the same thing: subspan() is provided for STL
     compatibility and sliced() is provided for Qt compatibility.
 
-    \sa subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), chopped()
+    \sa subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), chopped(), slice()
 */
 
 /*!
@@ -662,7 +662,7 @@
     These functions do the same thing: subspan() is provided for STL
     compatibility and sliced() is provided for Qt compatibility.
 
-    \sa subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), chopped()
+    \sa subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), chopped(), slice()
 */
 
 /*!
@@ -679,7 +679,40 @@
     This span must hold at least \a n elements (\c{E} >= \a n \e{and} size() >=
     \a n), otherwise the behavior is undefined.
 
-    \sa subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type),
+    \sa subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), chop()
+*/
+
+/*!
+    \fn template <typename T, size_t E> void QSpan<T,E>::chop(qsizetype n)
+    \since 6.9
+
+    Same as \c{*this = chopped(}\a{n}\c{)}.
+
+    This function is only available on \l{variable-fixed-spans}{variable-sized spans}.
+
+    \sa chopped()
+*/
+
+/*!
+    \fn template <typename T, size_t E> void QSpan<T,E>::slice(qsizetype pos)
+    \since 6.9
+
+    Same as \c{*this = sliced(}\a{pos}\c{)}.
+
+    This function is only available on \l{variable-fixed-spans}{variable-sized spans}.
+
+    \sa sliced()
+*/
+
+/*!
+    \fn template <typename T, size_t E> void QSpan<T,E>::slice(qsizetype pos, qsizetype n)
+    \since 6.9
+
+    Same as \c{*this = sliced(}\a{pos}\c{, }\a{n}\c{)}.
+
+    This function is only available on \l{variable-fixed-spans}{variable-sized spans}.
+
+    \sa sliced()
 */
 
 /*!