[doc] Clean-up QSpan docsv6.9.0-beta1

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 03e78e5d624d9752d76c7448d58c9d9d15a4dc18, 70dc8d3103fade380caec96f7531432cd8e8adb6, and ef5ac956c755daa9ea84dabfa1314d104e5c62e4. Pick-to: 6.8 Change-Id: I045824683f342079e33e89e3ee6f8e2e27a0acf5 Reviewed-by: Marc Mutz <marc.mutz@qt.io> (cherry picked from commit 10c844f0533daf657a1cbbbb96651e20e5d603ec) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> 

1 files changed, 35 insertions, 35 deletions

diff --git a/src/corelib/tools/qspan.qdoc b/src/corelib/tools/qspan.qdoc
index e70abef0f49..e7b5fe7dc0a 100644
--- a/src/corelib/tools/qspan.qdoc
+++ b/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,8 +115,8 @@
 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.
@@ -124,8 +124,8 @@
 \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,7 +210,7 @@

 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}
 */

 /*!
@@ -218,7 +218,7 @@

 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}
 */

 /*!
@@ -226,7 +226,7 @@

 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}
 */

 /*!
@@ -234,7 +234,7 @@

 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}
 */

 /*!
@@ -242,7 +242,7 @@

 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,7 +480,7 @@
 *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}
 */

 /*!
@@ -488,7 +488,7 @@

 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}
 */

 /*!
@@ -496,7 +496,7 @@

 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}
 */

 /*!
@@ -504,7 +504,7 @@

 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}
 */

 /*!
@@ -512,7 +512,7 @@

 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}
 */

 /*!
@@ -520,7 +520,7 @@

 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}
 */