Encourage use of QT_VERSION_CHECK()

Document that QT_VERSION should normally be compared against it,
rather than raw hex, and mildly update the example versions used in
docs. (Left the snippets testing old version, since the code in which
the #if-ery is used might actually make sense for those versions.)

Improve related documentation in the process.

Change-Id: Id3e97f41bfb0f81a117cf7b3a3ccd5f244e2a99a
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

3 files changed, 25 insertions, 15 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
index ced30cf32a..55ce52a2e7 100644
--- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
@@ -203,7 +203,7 @@ int boundedValue = qBound(minValue, myValue, maxValue);
 
 
 //! [16]
-#if QT_VERSION >= 0x040100
+#if QT_VERSION >= QT_VERSION_CHECK(4, 1, 0)
     QIcon icon = style()->standardIcon(QStyle::SP_TrashIcon);
 #else
     QPixmap pixmap = style()->standardPixmap(QStyle::SP_TrashIcon);
@@ -718,7 +718,7 @@ bool readConfiguration(const QFile &file)
 //! [qt-version-check]
 #include <QtGlobal>
 
-#if (QT_VERSION >= QT_VERSION_CHECK(5, 0, 0))
+#if QT_VERSION >= QT_VERSION_CHECK(5, 0, 0)
 #include <QtWidgets>
 #else
 #include <QtGui>
diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp
index 2301e5eb70..68247549f1 100644
--- a/src/corelib/global/qglobal.cpp
+++ b/src/corelib/global/qglobal.cpp
@@ -1302,17 +1302,24 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
 */
 
 /*!
-    \macro QT_VERSION_CHECK
+    \macro QT_VERSION_CHECK(major, minor, patch)
     \relates <QtGlobal>
 
-    Turns the major, minor and patch numbers of a version into an
-    integer, 0xMMNNPP (MM = major, NN = minor, PP = patch). This can
-    be compared with another similarly processed version id.
+    Turns the \a major, \a minor and \a patch numbers of a version into an
+    integer that encodes all three. When expressed in hexadecimal, this integer
+    is of form \c 0xMMNNPP wherein \c{0xMM ==} \a major, \c{0xNN ==} \a minor,
+    and \c{0xPP ==} \a patch. This can be compared with another similarly
+    processed version ID.
 
     Example:
 
     \snippet code/src_corelib_global_qglobal.cpp qt-version-check
 
+    \note the parameters are read as integers in the normal way, so should
+    normally be written in decimal (so a \c 0x prefix must be used if writing
+    them in hexadecimal). Thuse \c{QT_VERSION_CHECK(5, 15, 0)} is equal to \c
+    0x050e00, which could equally be written \c{QT_VERSION_CHECK(5, 0xe, 0)}.
+
     \sa QT_VERSION
 */
 
@@ -1320,19 +1327,22 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
     \macro QT_VERSION
     \relates <QtGlobal>
 
-    This macro expands a numeric value of the form 0xMMNNPP (MM =
-    major, NN = minor, PP = patch) that specifies Qt's version
-    number. For example, if you compile your application against Qt
-    4.1.2, the QT_VERSION macro will expand to 0x040102.
+    This macro expands to a numeric value of the same form as \l
+    QT_VERSION_CHECK() constructs, that specifies the version of Qt with which
+    code using it is compiled. For example, if you compile your application with
+    Qt 6.1.2, the QT_VERSION macro will expand to \c 0x060102, the same as
+    \c{QT_VERSION_CHECK(6, 1, 2)}. Note that this need not agree with the
+    version the application will find itself using at \e runtime.
 
-    You can use QT_VERSION to use the latest Qt features where
-    available.
+    You can use QT_VERSION to select the latest Qt features where available
+    while falling back to older implementations otherwise. Using
+    QT_VERSION_CHECK() for the value to compare with is recommended.
 
     Example:
 
     \snippet code/src_corelib_global_qglobal.cpp 16
 
-    \sa QT_VERSION_STR, qVersion()
+    \sa QT_VERSION_STR, QT_VERSION_CHECK(), qVersion()
 */
 
 /*!
diff --git a/src/corelib/global/qglobal.h b/src/corelib/global/qglobal.h
index 3fabac3888..429da158d3 100644
--- a/src/corelib/global/qglobal.h
+++ b/src/corelib/global/qglobal.h
@@ -53,11 +53,11 @@
 #endif
 
 /*
-   QT_VERSION is (major << 16) + (minor << 8) + patch.
+   QT_VERSION is (major << 16) | (minor << 8) | patch.
 */
 #define QT_VERSION      QT_VERSION_CHECK(QT_VERSION_MAJOR, QT_VERSION_MINOR, QT_VERSION_PATCH)
 /*
-   can be used like #if (QT_VERSION >= QT_VERSION_CHECK(4, 4, 0))
+   can be used like #if (QT_VERSION >= QT_VERSION_CHECK(6, 4, 0))
 */
 #define QT_VERSION_CHECK(major, minor, patch) ((major<<16)|(minor<<8)|(patch))