Long live QT6_{DECL,IMPL,CALL}_NEW_OVERLOAD!

We have in the past found ourselves in need of disambiguating new
overloads from older, QT_REMOVED_SINCE'ed ones, which we usually did
by adding a defaulted int argument, cf. e.g. QMetaType::id().

The problem with a defaulted int argument is twofold: First, an int is
a valid argument type, and users may get confused as to its meaning
when presented with the signature in the IDEs auto-completion popup,
and a lot of things implicitly convert to an int, so any errornous
parameter passing may stay unnoticed until we remove these fake
arguments come Qt 7.

Second, this way of doing things requires a lot of ifdef'ery to keep
the additional argument out of both the docs and future Qt 7 builds.

The solution presented in this patch is to create a tag type,
QDisambiguated_t, which a) more clearly communicates its purpose and
b) doesn't implicitly convert from anything.

To help with the invariably ugly ifdef'ery, provide a set of macros
that hide this stuff from qdoc and Qt 7 builds.

Use the macros to replace the fake int arguments that were added for
6.4.

Pick-to: 6.4
Change-Id: I6916f38c8eb9793ad6dea5f61e7e5fff7e75e273
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

4 files changed, 46 insertions, 1 deletions

diff --git a/src/corelib/global/qglobal.h b/src/corelib/global/qglobal.h
index bbff1d2926..d077057aaa 100644
--- a/src/corelib/global/qglobal.h
+++ b/src/corelib/global/qglobal.h
@@ -95,6 +95,40 @@
 #  error Qt major version not 6 or 7
 #endif
 
+/* Macro and tag type to help overload resolution on functions
+   that are, e.g., QT_REMOVED_SINCE'ed. Example use:
+
+   #if QT_CORE_REMOVED_SINCE(6, 4)
+   int size() const;
+   #endif
+   qsizetype size(QT6_DECL_NEW_OVERLOAD) const;
+
+   in the normal cpp file:
+
+   qsizetype size(QT6_IMPL_NEW_OVERLOAD) const {
+      ~~~
+   }
+
+   in removed_api.cpp:
+
+   int size() const { return int(size(QT6_CALL_NEW_OVERLOAD)); }
+*/
+#ifdef Q_CLANG_QDOC
+# define QT6_DECL_NEW_OVERLOAD
+# define QT6_DECL_NEW_OVERLOAD_TAIL
+# define QT6_IMPL_NEW_OVERLOAD
+# define QT6_IMPL_NEW_OVERLOAD_TAIL
+# define QT6_CALL_NEW_OVERLOAD
+# define QT6_CALL_NEW_OVERLOAD_TAIL
+#else
+# define QT6_DECL_NEW_OVERLOAD QT6_ONLY(Qt::Disambiguated_t = Qt::Disambiguated)
+# define QT6_DECL_NEW_OVERLOAD_TAIL QT6_ONLY(, QT6_DECL_NEW_OVERLOAD)
+# define QT6_IMPL_NEW_OVERLOAD QT6_ONLY(Qt::Disambiguated_t)
+# define QT6_IMPL_NEW_OVERLOAD_TAIL QT6_ONLY(, QT6_IMPL_NEW_OVERLOAD)
+# define QT6_CALL_NEW_OVERLOAD QT6_ONLY(Qt::Disambiguated)
+# define QT6_CALL_NEW_OVERLOAD_TAIL QT6_ONLY(, QT_CALL_NEW_OVERLOAD)
+#endif
+
 /* These two macros makes it possible to turn the builtin line expander into a
  * string literal. */
 #define QT_STRINGIFY2(x) #x
diff --git a/src/corelib/global/qnamespace.h b/src/corelib/global/qnamespace.h
index dd70e91a8f..5c8ed2e8e5 100644
--- a/src/corelib/global/qnamespace.h
+++ b/src/corelib/global/qnamespace.h
@@ -1580,6 +1580,11 @@ namespace Qt {
     };
     inline constexpr Initialization Uninitialized = Initialization::Uninitialized;
 
+    struct Disambiguated_t {
+        explicit Disambiguated_t() = default;
+    };
+    inline constexpr Disambiguated_t Disambiguated{};
+
     enum CoordinateSystem {
         DeviceCoordinates,
         LogicalCoordinates
diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index 000001c1bf..23e3e9736b 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -3010,6 +3010,11 @@
 */
 
 /*!
+    \enum Qt::Disambiguated_t
+    \internal
+*/
+
+/*!
     \enum Qt::CoordinateSystem
     \since 4.6
 
diff --git a/src/corelib/tools/qhashfunctions.h b/src/corelib/tools/qhashfunctions.h
index 58f4afc94f..e9da071803 100644
--- a/src/corelib/tools/qhashfunctions.h
+++ b/src/corelib/tools/qhashfunctions.h
@@ -150,7 +150,8 @@ Q_CORE_EXPORT Q_DECL_PURE_FUNCTION size_t qHash(const QByteArray &key, size_t se
 Q_CORE_EXPORT Q_DECL_PURE_FUNCTION size_t qHash(const QByteArrayView &key, size_t seed = 0) noexcept;
 #else
 Q_CORE_EXPORT Q_DECL_PURE_FUNCTION size_t qHash(QByteArrayView key, size_t seed = 0) noexcept;
-inline Q_DECL_PURE_FUNCTION size_t qHash(const QByteArray &key, size_t seed = 0 QT6_ONLY(, int = 0)) noexcept
+inline Q_DECL_PURE_FUNCTION size_t qHash(const QByteArray &key, size_t seed = 0
+        QT6_DECL_NEW_OVERLOAD_TAIL) noexcept
 { return qHash(qToByteArrayViewIgnoringNull(key), seed); }
 #endif