docs: promote QBasicTimer usage by making it more visible

Deduplicate some API docs.

Mention that it's a RAII class, to make it more appealing to users.
Copied the "RAII" note and link from QSemaphoreReleaser's API docs.

Change-Id: I53ced6eb7c2ab55ffc04e70c250b5f5639406911
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
(cherry picked from commit e1fdfe9da8ccdeed9af602897232a513884b0515)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/doc/src/timers.qdoc

@@ -15,6 +15,15 @@
     regular intervals until you explicitly call QObject::killTimer()
     with that timer ID.
 
+    Instead of handling timer IDs directly, you can use \l QBasicTimer.
+    QBasicTimer is a value-class,
+    \l{http://en.cppreference.com/w/cpp/language/raii}{RAII} wrapper around
+    a timer ID. You start the timer with \l{QBasicTimer::start()}, and stop
+    it with \l{QBasicTimer::stop()} (the latter is also called upon destruction).
+    To use QBasicTimer, you must reimplement \l{QObject::timerEvent()}{timerEvent()}
+    in your class (which must be a sub-class of QObject), and handle the
+    timer event there.
+
     For this mechanism to work, the application must run in an event
     loop. You cat start an event loop with QApplication::exec(). When a
     timer fires, the application sends a QTimerEvent, and the flow of
@@ -87,10 +96,4 @@
 
     Every second, QChronoTimer will call the QWidget::update() slot to
     refresh the clock's display.
-
-    If you already have a QObject subclass and want an easy
-    optimization, you can use QBasicTimer instead of QTimer. With
-    QBasicTimer, you must reimplement
-    \l{QObject::timerEvent()}{timerEvent()} in your QObject subclass
-    and handle the timeout there.
 */

src/corelib/kernel/qchronotimer.cpp

@@ -97,15 +97,7 @@ QT_BEGIN_NAMESPACE
     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()
+    \include timers-common.qdocinc q-chrono-timer-alternatives
-    for your object and reimplement the QObject::timerEvent() event handler
-    in your class (which must be a sub-class of QObject). The disadvantage
-    is that timerEvent() does not support such high-level features as
-    single-shot timers or signals.
-
-    Another alternative is QBasicTimer. It is typically less cumbersome
-    than using QObject::startTimer() directly. See \l{Timers} for an
-    overview of all three approaches.
 
     Some operating systems limit the number of timers that may be used;
     Qt does its best to work around these limitations.

src/corelib/kernel/qtimer.cpp

@@ -104,15 +104,7 @@ QT_BEGIN_NAMESPACE
     \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()
+    \include timers-common.qdocinc q-chrono-timer-alternatives
-    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
-    high-level features as single-shot timers or signals.
-
-    Another alternative is QBasicTimer. It is typically less
-    cumbersome than using QObject::startTimer()
-    directly. See \l{Timers} for an overview of all three approaches.
 
     Some operating systems limit the number of timers that may be
     used; Qt tries to work around these limitations.

src/corelib/kernel/timers-common.qdocinc

@@ -0,0 +1,24 @@
+// Copyright (C) 2024 Ahmad Samir <a.samirh78@gmail.com>
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+//! [q-chrono-timer-alternatives]
+    Another alternative is reimplementing the QObject::timerEvent() method
+    in your class (which must be a sub-class of QObject), and using one of
+    the following approaches:
+
+    \list
+    \li Using QBasicTimer, a lightweight value-class wrapping a timer
+    ID. You can start the timer with QBasicTimer::start() and stop it with
+    QBasicTimer::stop(). You can handle the event in your reimplemneted
+    timerEvent().
+
+    \li A more low-level method is manipulating the timer IDs directly.
+    To start the timer call QObject::startTimer(), storing the returned
+    ID. To stop the timer call QObject::killTimer(). You can handle the event
+    in your reimplemented timerEvent(). This approach is typically more
+    cumbersome than using QBasicTimer.
+    \endlist
+
+    A disadvantage of using timerEvent() is that some high-level features,
+    such as single-shot timers and signals, aren't supported.
+//! [q-chrono-timer-alternatives]