QTimer: QChronoTimer isn't necessarily going to supersede QTimer

... since no consensus has been reached about what to do in Qt7 (whether
to fold QChronoTimer back into QTimer or let QTimer be as-is to not
break any existing code and use QChronoTimer in new code).

Task-number: QTBUG-128426
Change-Id: I7d09b803b4f0df3ea7f48a5d900d0ae4be721d7b
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit 87030778969165a285af2d919d6d7293e8078b6a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/doc/src/timers.qdoc

@@ -31,16 +31,17 @@
     stop all timers in the object's thread; it is not possible to
     start timers for objects in another thread.
 
-    The main API for the timer functionality was \l QTimer. QTimer stores
+    The main API for the timer functionality is \l QTimer. QTimer stores
     the interval in a signed integer, which limits the maximum interval it
     supports to the number of milliseconds that can fit in a signed integer
     (in practice, this is a period of around 24 days).
 
-    Qt 6.8 introduced the \l QChronoTimer class to replace QTimer. QChronoTimer
-    stores the interval as \c std::chrono::nanoseconds, which means that
-    the maximum interval it supports is around 292 years. This mitigates
-    the chances of integer overflow that QTimer had if the interval was more
-    than \c{std::numeric_limits<int>::max()}.
+    Qt 6.8 introduced the \l QChronoTimer class. The main difference between
+    the two classes is that QChronoTimer supports a larger interval range
+    and a higher precision (\c std::chrono::nanoseconds). For QTimer the
+    maximum supported interval is ±24 days, whereas for QChronoTimer it is
+    ±292 years. If you only need millisecond resolution and ±24 days range,
+    you can continue to use \l QTimer.
 
     The accuracy of the timers depends on the underlying operating system.
     Windows 2000 has 15ms accuracy; other systems that we have tested can

src/corelib/kernel/qchronotimer.cpp

@@ -92,6 +92,11 @@ QT_BEGIN_NAMESPACE
 
     \section1 Alternatives to QChronoTimer
 
+    QChronoTimer provides nanosecond resolution and a ±292 years range
+    (less chances of integer overflow if the interval is longer than \c
+    std::numeric_limits<int>::max()). If you only need millisecond resolution
+    and ±24 days range, you can continue to use the classical QTimer class
+
     An alternative to using QChronoTimer is to call QObject::startTimer()
     for your object and reimplement the QObject::timerEvent() event handler
     in your class (which must be a sub-class of QObject). The disadvantage

src/corelib/kernel/qtimer.cpp

@@ -74,13 +74,6 @@ QT_BEGIN_NAMESPACE
     more and more platforms, we expect that zero-millisecond
     QTimer objects will gradually be replaced by \l{QThread}s.
 
-    \note Since Qt 6.8 this class is superseded by \l{QChronoTimer}.
-    The maximum interval QTimer supports is limited by the number of
-    milliseconds that would fit in an \c int (which is around 24 days);
-    whereas QChronoTimer stores its interval as \c std::chrono::nanoseconds
-    (which raises that limit to ±292 years), that is, there is
-    less chance of integer overflow with QChronoTimer.
-
     \section1 Accuracy and Timer Resolution
 
     The accuracy of timers depends on the underlying operating system
@@ -103,7 +96,15 @@ QT_BEGIN_NAMESPACE
 
     \section1 Alternatives to QTimer
 
-    An alternative to using QTimer is to call QObject::startTimer()
+    Qt 6.8 introduced QChronoTimer. The main difference between the two
+    classes, is that QChronoTimer supports a larger interval range and a
+    higher precision (\c std::chrono::nanoseconds). For QTimer the maximum
+    supported interval is ±24 days, whereas for QChronoTimer it is ±292
+    years (less chances of interger overflow with intervals longer than
+    \c std::numeric_limits<int>::max()). If you only need millisecond
+    resolution and ±24 days range, you can continue to use QTimer.
+
+    Another alternative is to call QObject::startTimer()
     for your object and reimplement the QObject::timerEvent() event
     handler in your class (which must inherit QObject). The
     disadvantage is that timerEvent() does not support such