[doc] Clean-up QSpan docs

QSpan docs use \target commands together with the section headers, to
simplify linking to certain parts of the docs. This approach has its
own drawbacks, though, because the \target link is rendered as-is.
This patch improves usage of the \target commands, making the links
look better.
It does the following changes:
* Moves the \target commands before the related \section2 commands, so
  that the section header is visible when following the \target's link.
* Replaces the \target links with the actual section names in the \sa
  and other places of the docs where the links do not have the custom
  text, because otherwise the target names are actually visible in the
  docs instead of the section headers.

Amends 03e78e5,
70dc8d3, and
ef5ac95.

Pick-to: 6.8
Change-Id: I045824683f342079e33e89e3ee6f8e2e27a0acf5
Reviewed-by: Marc Mutz <[email protected]>
(cherry picked from commit 10c844f)
Reviewed-by: Qt Cherry-pick Bot <[email protected]>

src/corelib/tools/qspan.qdoc

@@ -22,7 +22,7 @@
 
     Unlike views such as QStringView, QLatin1StringView and QUtf8StringView,
     referenced data can be modified through a QSpan object. To prevent this,
-    construct a QSpan over a \c{const T} (see \l{const-mutable-spans}):
+    construct a QSpan over a \c{const T} (see \l{Const and Mutable Spans}):
 
     \code
     int numbers[] = {0, 1, 2};
@@ -33,8 +33,8 @@
     cspan[0] = 0; // ERROR: cspan[0] is read-only
     \endcode
 
-    \section2 Variable-Size and Fixed-Size Spans
     \target variable-fixed-spans
+    \section2 Variable-Size and Fixed-Size Spans
 
     A QSpan can be \e{fixed-size} or \e{variable-sized}.
 
@@ -62,8 +62,8 @@
     The opposite direction (variable-length into fixed-length) has the
     precondition that both span's sizes must match.
 
-    \section2 Const and Mutable Spans
     \target const-mutable-spans
+    \section2 Const and Mutable Spans
 
     Unlike with owning containers, \c{const} is \e{shallow} in QSpan: you can
     still modify the data through a const QSpan (but not through a
@@ -79,8 +79,8 @@
     *span.cbegin() = -1; // ERROR: cannot assign through a const_iterator
     \endcode
 
-    \section2 Other Properties
     \target other-span-properties
+    \section2 Other Properties
 
     QSpan should be passed by value, not by reference-to-const:
 
@@ -92,8 +92,8 @@
     \c{QSpan<T,N>} is a \e{Literal Type}, regardless of whether \c{T} is a
     Literal Type or not.
 
-    \section2 QSpan vs. std::span
     \target span-STL
+    \section2 QSpan vs. std::span
 
     QSpan is closely modelled after
     \l{https://en.cppreference.com/w/cpp/container/span}{std::span}, but has a
@@ -115,17 +115,17 @@
     with the rest of Qt containers. QSpan template arguments still use size_t
     to avoid introducing unnecessary error conditions (negative sizes).
 
-    \section2 Compatible Iterators
     \target span-compatible-iterators
+    \section2 Compatible Iterators
 
     QSpan can be constructed from an iterator and size or from an
     iterator pair, provided the iterators are \e{compatible} ones.
     Eventually, this should mean C++20 \c{std::contiguous_iterator} and
     \c{std::sentinel_for}, but while Qt still supports C++17, only raw pointers
     are considered contiguous iterators.
 
-    \section2 Compatible Ranges
     \target span-compatible-ranges
+    \section2 Compatible Ranges
 
     QSpan can also be constructed from a \e{compatible} range. A range is
     compatible if it has \l{span-compatible-iterators}{compatible iterators}.
@@ -144,7 +144,7 @@
 
     This alias is provided for compatbility with the STL.
 
-    \sa value_type, pointer, {const-mutable-spans}
+    \sa value_type, pointer, {Const and Mutable Spans}
 */
 
 /*!
@@ -154,7 +154,7 @@
 
     This alias is provided for compatbility with the STL.
 
-    \sa element_type, {const-mutable-spans}
+    \sa element_type, {Const and Mutable Spans}
 */
 
 /*!
@@ -180,7 +180,7 @@
 
     This alias is provided for compatbility with the STL.
 
-    \sa element_type, const_pointer, reference, iterator, {const-mutable-spans}
+    \sa element_type, const_pointer, reference, iterator, {Const and Mutable Spans}
 */
 
 /*!
@@ -190,7 +190,7 @@
 
     This alias is provided for compatbility with the STL.
 
-    \sa element_type, pointer, const_reference, const_iterator, {const-mutable-spans}
+    \sa element_type, pointer, const_reference, const_iterator, {Const and Mutable Spans}
 */
 
 /*!
@@ -200,7 +200,7 @@
 
     This alias is provided for compatbility with the STL.
 
-    \sa element_type, const_reference, pointer, {const-mutable-spans}
+    \sa element_type, const_reference, pointer, {Const and Mutable Spans}
 */
 
 /*!
@@ -210,39 +210,39 @@
 
     This alias is provided for compatbility with the STL.
 
-    \sa element_type, reference, const_pointer, {const-mutable-spans}
+    \sa element_type, reference, const_pointer, {Const and Mutable Spans}
 */
 
 /*!
     \typedef QSpan::iterator
 
     An alias for \c{T*} and \c{pointer}, respectively. Includes the \c{const}, if any.
 
-    \sa pointer, const_iterator, reverse_iterator, {const-mutable-spans}
+    \sa pointer, const_iterator, reverse_iterator, {Const and Mutable Spans}
 */
 
 /*!
     \typedef QSpan::const_iterator
 
     An alias for \c{const T*} and \c{const_pointer}, respectively.
 
-    \sa const_pointer, iterator, const_reverse_iterator, {const-mutable-spans}
+    \sa const_pointer, iterator, const_reverse_iterator, {Const and Mutable Spans}
 */
 
 /*!
     \typedef QSpan::reverse_iterator
 
     An alias for \c{std::reverse_iterator<iterator>}. Includes the \c{const}, if any.
 
-    \sa iterator, const_reverse_iterator, {const-mutable-spans}
+    \sa iterator, const_reverse_iterator, {Const and Mutable Spans}
 */
 
 /*!
     \typedef QSpan::const_reverse_iterator
 
     An alias for \c{std::reverse_iterator<const_iterator>}.
 
-    \sa const_iterator, reverse_iterator, {const-mutable-spans}
+    \sa const_iterator, reverse_iterator, {Const and Mutable Spans}
 */
 
 /*!
@@ -271,7 +271,7 @@
     \c{std::dynamic_extent}. In other words: only fixed-zero-sized or variable-sized spans
     are default-constructible.
 
-    \sa extent, {variable-fixed-spans}
+    \sa extent, {Variable-Size and Fixed-Size Spans}
 */
 
 /*!
@@ -361,7 +361,7 @@
 
     \note If \c{E} is not \c{std::dynamic_extent} and the size of \a il is not \c{E}, the behavior is undefined.
 
-    \sa {const-mutable-spans}
+    \sa {Const and Mutable Spans}
 */
 
 //
@@ -409,7 +409,7 @@
     The index must be in range, that is, \a idx >= 0 and \a idx < size(),
     otherwise the behavior is undefined.
 
-    \sa front(), back(), size(), empty(), {const-mutable-spans}
+    \sa front(), back(), size(), empty(), {Const and Mutable Spans}
 */
 
 /*!
@@ -419,7 +419,7 @@
 
     The span must not be empty, otherwise the behavior is undefined.
 
-    \sa operator[](), back(), size(), empty(), {const-mutable-spans}
+    \sa operator[](), back(), size(), empty(), {Const and Mutable Spans}
 */
 
 /*!
@@ -429,7 +429,7 @@
 
     The span must not be empty, otherwise the behavior is undefined.
 
-    \sa operator[](), front(), size(), empty(), {const-mutable-spans}
+    \sa operator[](), front(), size(), empty(), {Const and Mutable Spans}
 */
 
 /*!
@@ -439,7 +439,7 @@
 
     The same as calling begin().
 
-    \sa begin(), front(), {const-mutable-spans}
+    \sa begin(), front(), {Const and Mutable Spans}
 */
 
 //
@@ -454,7 +454,7 @@
     Because QSpan iterators are just pointers, this is the same as calling
     data().
 
-    \sa end(), cbegin(), rbegin(), crbegin(), data(), {const-mutable-spans}
+    \sa end(), cbegin(), rbegin(), crbegin(), data(), {Const and Mutable Spans}
 */
 
 /*!
@@ -465,7 +465,7 @@
     Because QSpan iterators are just pointers, this it the same as calling
     \c{data() + size()}.
 
-    \sa begin(), cend(), rend(), crend(), data(), size(), {const-mutable-spans}
+    \sa begin(), cend(), rend(), crend(), data(), size(), {Const and Mutable Spans}
 */
 
 /*!
@@ -480,47 +480,47 @@
     *span.cbegin() = 42; // ERROR: cannot assign through a const_iterator
     \endcode
 
-    \sa cend(), begin(), crbegin(), rbegin(), data(), {const-mutable-spans}
+    \sa cend(), begin(), crbegin(), rbegin(), data(), {Const and Mutable Spans}
 */
 
 /*!
     \fn template <typename T, size_t E> auto QSpan<T, E>::cend() const
 
     Returns a const_iterator pointing to one past the end of the span.
 
-    \sa cbegin(), end(), crend(), rend(), data(), size(), {const-mutable-spans}
+    \sa cbegin(), end(), crend(), rend(), data(), size(), {Const and Mutable Spans}
 */
 
 /*!
     \fn template <typename T, size_t E> auto QSpan<T, E>::rbegin() const
 
     Returns a reverse_iterator pointing to the beginning of the reversed span.
 
-    \sa rend(), crbegin(), begin(), cbegin(), {const-mutable-spans}
+    \sa rend(), crbegin(), begin(), cbegin(), {Const and Mutable Spans}
 */
 
 /*!
     \fn template <typename T, size_t E> auto QSpan<T, E>::rend() const
 
     Returns a reverse_iterator pointing to one past the end of the reversed span.
 
-    \sa rbegin(), crend(), end(), cend(), {const-mutable-spans}
+    \sa rbegin(), crend(), end(), cend(), {Const and Mutable Spans}
 */
 
 /*!
     \fn template <typename T, size_t E> auto QSpan<T, E>::crbegin() const
 
     Returns a const_reverse_iterator pointing to the beginning of the reversed span.
 
-    \sa crend(), rbegin(), cbegin(), begin(), {const-mutable-spans}
+    \sa crend(), rbegin(), cbegin(), begin(), {Const and Mutable Spans}
 */
 
 /*!
     \fn template <typename T, size_t E> auto QSpan<T, E>::crend() const
 
     Returns a const_reverse_iterator pointing to one past the end of the reversed span.
 
-    \sa crbegin(), rend(), cend(), end(), {const-mutable-spans}
+    \sa crbegin(), rend(), cend(), end(), {Const and Mutable Spans}
 */
 
 //
@@ -567,7 +567,7 @@
     size() >= \c{Offset}), otherwise the behavior is undefined.
 
     \sa subspan(QSpan<T,E>::size_type), subspan(), first(), last()
-    \sa {variable-fixed-spans}
+    \sa {Variable-Size and Fixed-Size Spans}
 */
 
 /*!
@@ -585,7 +585,7 @@
     behavior is undefined.
 
     \sa subspan(QSpan<T,E>::size_type, QSpan<T,E>::size_type), subspan(), first(), last()
-    \sa {variable-fixed-spans}
+    \sa {Variable-Size and Fixed-Size Spans}
 */
 
 //
@@ -728,7 +728,7 @@
     \note \c{q20::dynamic_extent} is a C++17 backport of C++20's
     \l{https://en.cppreference.com/w/cpp/container/span/dynamic_extent}{\c{std::dynamic_extent}}.
 
-    \sa as_writable_bytes(), size_bytes(), {const-mutable-spans}
+    \sa as_writable_bytes(), size_bytes(), {Const and Mutable Spans}
 */
 
 /*!
@@ -747,5 +747,5 @@
     \note \c{q20::dynamic_extent} is a C++17 backport of C++20's
     \l{https://en.cppreference.com/w/cpp/container/span/dynamic_extent}{\c{std::dynamic_extent}}.
 
-    \sa as_bytes(), size_bytes(), {const-mutable-spans}
+    \sa as_bytes(), size_bytes(), {Const and Mutable Spans}
 */