Un-deprecate qSwap()

It seems to have fallen prey to the mass-deprecation of <QtAlgorithms>
in Qt 5.2. Since it didn't actually duplicate STL functionality, that
was uncalled-for: Unlike std::swap(), it's ADL-enabled, so the docs
were wrong to suggest replacing it with std::swap instead.

In fact, the tony-table that 5957f245c6c77c98d7e90d614c9fe2cdbfe7e8e6
added to qalgorithms.qdoc didn't include qSwap(), yet, qSwap() was
marked as deprecated.

Un-deprecate and expand the discussion to more faithfully represent
its value, without going into the depths of teaching how to swap
correctly in C++ (link to boost.org and cppreference.com for that
instead).

Remove the example that used qSwap() on doubles, which is precisely
_not_ how you should use it.

Amends 5957f245c6c77c98d7e90d614c9fe2cdbfe7e8e6(!).

[ChangeLog][QtCore] Un-deprecated qSwap().

Pick-to: 6.5 6.2 5.15
Change-Id: I4981005ba71b0d1824f2a46897145255fa66a7ea
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
(cherry picked from commit aa19704bbc35d5310b33a9fbe2added77470a836)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp

@@ -1,15 +1,6 @@
 // Copyright (C) 2016 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
-//! [0]
-double pi = 3.14;
-double e = 2.71;
-
-qSwap(pi, e);
-// pi == 2.71, e == 3.14
-//! [0]
-
-
 //! [1]
 QList<Employee *> list;
 list.append(new Employee("Blackpool", "Stephen"));

src/corelib/global/qswap.qdoc

@@ -1,14 +1,38 @@
 // Copyright (C) 2022 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
-/*! \fn template <typename T> void qSwap(T &var1, T &var2)
+/*!
+    \fn template <typename T> void qSwap(T &lhs, T &rhs)
     \relates <QtSwap>
-    \deprecated
 
-    Use \c std::swap instead.
+    Exchanges the values of variables \a lhs and \a rhs,
+    taking type-specific \c{swap()} overloads into account.
 
-    Exchanges the values of variables \a var1 and \a var2.
+    This function is Qt's version of
+    \l{https://www.boost.org/doc/libs/release/libs/core/doc/html/core/swap.html}{\c{boost::swap()}},
+    and is equivalent to
+    \code
+    using std::swap;   // bring std::swap into scope (for built-in types)
+    swap(lhs, rhs);    // unqualified call (picks up type-specific overloads
+                       // via Argument-Dependent Lookup, or falls back to std::swap)
+    \endcode
 
-    Example:
-    \snippet code/doc_src_qalgorithms.cpp 0
+    Use this function primarily in generic code, where you would traditionally
+    have written the above two lines, because you don't know anything about \c{T}.
+
+    If you already know what \c{T} is, then use one of the following options, in
+    order of preference:
+
+    \list
+    \li \c{lhs.swap(rhs);} if such a member-swap exists
+    \li \c{std::swap(lhs, rhs);} if no type-specific \c{swap()} exists
+    \endlist
+
+    See
+    \l{https://www.boost.org/doc/libs/release/libs/core/doc/html/core/swap.html}{\c{boost::swap()} on boost.org}
+    for more details.
+
+    See also
+    \l{https://en.cppreference.com/w/cpp/algorithm/swap}{\c{std::swap} on cppreference.com},
+    \l{https://en.cppreference.com/w/cpp/named_req/Swappable}{\c{Swappable} on cppreference.com}.
 */