Doc: Ensure deprecated APIs in Gui are documented as such

Added missing #if-ery and deprecation macros to a QFont constructor
that was only documented as deprecated.

Fixes: QTBUG-94521
Fixes: QTBUG-95310
Pick-to: 6.2 6.1
Change-Id: I3d0418a3f7dca191a9068cc22627fe4deb7c53c5
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

4 files changed, 57 insertions, 28 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 73a591f34c..ff9ec52b09 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -99,46 +99,55 @@ QEnterEvent::~QEnterEvent()
 
 /*!
    \fn QPoint QEnterEvent::globalPos() const
+   \deprecated [6.0] Use globalPosition() instead.
 
    Returns the global position of the mouse cursor \e{at the time of the event}.
 */
 /*!
    \fn int QEnterEvent::globalX() const
+   \deprecated [6.0] Use globalPosition().x() instead.
 
    Returns the global position on the X-axis of the mouse cursor \e{at the time of the event}.
 */
 /*!
    \fn int QEnterEvent::globalY() const
+   \deprecated [6.0] Use globalPosition().y() instead.
 
    Returns the global position on the Y-axis of the mouse cursor \e{at the time of the event}.
 */
 /*!
    \fn QPointF QEnterEvent::localPos() const
+   \deprecated [6.0] Use position() instead.
 
    Returns the mouse cursor's position relative to the receiving widget.
 */
 /*!
    \fn QPoint QEnterEvent::pos() const
+   \deprecated [6.0] Use position().toPoint() instead.
 
    Returns the position of the mouse cursor relative to the receiving widget.
 */
 /*!
    \fn QPointF QEnterEvent::screenPos() const
+   \deprecated [6.0] Use globalPosition() instead.
 
    Returns the position of the mouse cursor relative to the receiving screen.
 */
 /*!
    \fn QPointF QEnterEvent::windowPos() const
+   \deprecated [6.0] Use scenePosition() instead.
 
    Returns the position of the mouse cursor relative to the receiving window.
 */
 /*!
    \fn int QEnterEvent::x() const
+   \deprecated [6.0] Use position().x() instead.
 
    Returns the x position of the mouse cursor relative to the receiving widget.
 */
 /*!
    \fn int QEnterEvent::y() const
+   \deprecated [6.0] Use position().y() instead.
 
    Returns the y position of the mouse cursor relative to the receiving widget.
 */
@@ -630,7 +639,6 @@ bool QSinglePointEvent::isEndEvent() const
     \endcode
 */
 
-
 /*!
     \class QMouseEvent
     \ingroup events
@@ -779,7 +787,7 @@ QMouseEvent::~QMouseEvent()
 
 /*!
     \since 5.3
-    \deprecated in 6.0: use pointingDevice()
+    \deprecated [6.0] Use pointingDevice() instead.
 
     Returns information about the mouse event source.
 
@@ -818,6 +826,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn QPointF QMouseEvent::localPos() const
+    \deprecated [6.0] Use position() instead.
 
     \since 5.0
 
@@ -845,6 +854,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn QPointF QMouseEvent::windowPos() const
+    \deprecated [6.0] Use scenePosition() instead.
 
     \since 5.0
 
@@ -860,6 +870,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn QPointF QMouseEvent::screenPos() const
+    \deprecated [6.0] Use globalPosition() instead.
 
     \since 5.0
 
@@ -884,6 +895,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn QPoint QMouseEvent::globalPos() const
+    \deprecated [6.0] Use globalPosition().toPoint() instead.
 
     Returns the global position of the mouse cursor \e{at the time
     of the event}. This is important on asynchronous window systems
@@ -897,6 +909,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn int QMouseEvent::x() const
+    \deprecated [6.0] Use position().x() instead.
 
     Returns the x position of the mouse cursor, relative to the
     widget that received the event.
@@ -906,6 +919,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn int QMouseEvent::y() const
+    \deprecated [6.0] Use position().y() instead.
 
     Returns the y position of the mouse cursor, relative to the
     widget that received the event.
@@ -915,6 +929,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn int QMouseEvent::globalX() const
+    \deprecated [6.0] Use globalPosition().x() instead.
 
     Returns the global x position of the mouse cursor at the time of
     the event.
@@ -924,6 +939,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn int QMouseEvent::globalY() const
+    \deprecated [6.0] Use globalPosition().y() instead.
 
     Returns the global y position of the mouse cursor at the time of
     the event.
@@ -981,6 +997,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn QPoint QHoverEvent::pos() const
+    \deprecated [6.0] Use position().toPoint() instead.
 
     Returns the position of the mouse cursor, relative to the widget
     that received the event.
@@ -1006,6 +1023,7 @@ Qt::MouseEventFlags QMouseEvent::flags() const
 
 /*!
     \fn const QPointF &QHoverEvent::posF() const
+    \deprecated [6.0] Use position() instead.
 
     Returns the position of the mouse cursor, relative to the widget
     that received the event.
@@ -1097,7 +1115,7 @@ QHoverEvent::~QHoverEvent()
 /*!
     \fn Qt::MouseEventSource QWheelEvent::source() const
     \since 5.5
-    \deprecated in 6.0: use pointingDevice()
+    \deprecated [6.0] Use pointingDevice() instead.
 
     Returns information about the wheel event source.
 
@@ -1226,7 +1244,7 @@ bool QWheelEvent::isEndEvent() const
     \li scrolling is about to begin, but the distance did not yet change (Qt::ScrollBegin),
     \li or scrolling has ended and the distance did not change anymore (Qt::ScrollEnd).
     \endlist
-    \note On X11 this value is driver specific and unreliable, use angleDelta() instead
+    \note On X11 this value is driver-specific and unreliable, use angleDelta() instead.
 */
 
 /*!
@@ -1775,6 +1793,7 @@ QPlatformSurfaceEvent::~QPlatformSurfaceEvent()
 
 /*!
     \fn const QRegion &QExposeEvent::region() const
+    \deprecated [6.0] Use QPaintEvent instead.
 
     Returns the window area that has been exposed. The region is given in local coordinates.
 */
@@ -2606,6 +2625,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn QPoint QTabletEvent::pos() const
+    \deprecated [6.0] Use position().toPoint() instead.
 
     Returns the position of the device, relative to the widget that
     received the event.
@@ -2618,6 +2638,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn int QTabletEvent::x() const
+    \deprecated [6.0] Use position().x() instead.
 
     Returns the x position of the device, relative to the widget that
     received the event.
@@ -2627,6 +2648,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn int QTabletEvent::y() const
+    \deprecated [6.0] Use position().y() instead.
 
     Returns the y position of the device, relative to the widget that
     received the event.
@@ -2648,6 +2670,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn QPoint QTabletEvent::globalPos() const
+    \deprecated [6.0] Use globalPosition().toPoint() instead.
 
     Returns the global position of the device \e{at the time of the
     event}. This is important on asynchronous windows systems like X11;
@@ -2660,6 +2683,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn int QTabletEvent::globalX() const
+    \deprecated [6.0] Use globalPosition().x() instead.
 
     Returns the global x position of the mouse pointer at the time of
     the event.
@@ -2669,6 +2693,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn int QTabletEvent::globalY() const
+    \deprecated [6.0] Use globalPosition().y() instead.
 
     Returns the global y position of the tablet device at the time of
     the event.
@@ -2678,6 +2703,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn qint64 QTabletEvent::uniqueId() const
+    \deprecated [6.0] Use pointingDevice().uniqueId() instead.
 
     Returns a unique ID for the current device, making it possible
     to differentiate between multiple devices being used at the same
@@ -2701,6 +2727,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn const QPointF &QTabletEvent::posF() const
+    \deprecated [6.0] Use position() instead.
 
     Returns the position of the device, relative to the widget that
     received the event.
@@ -2713,7 +2740,7 @@ QTabletEvent::~QTabletEvent()
 
 /*!
     \fn const QPointF &QTabletEvent::globalPosF() const
-
+    \deprecated [6.0] Use globalPosition() instead.
     Returns the global position of the device \e{at the time of the
     event}. This is important on asynchronous windows systems like X11;
     whenever you move your widgets around in response to mouse events,
@@ -2791,9 +2818,9 @@ QTabletEvent::~QTabletEvent()
     \sa Qt::NativeGestureType, QGestureEvent, QWheelEvent
 */
 
+#if QT_DEPRECATED_SINCE(6, 2)
 /*!
-    \deprecated
-    Use the other constructor, because \a intValue is no longer stored separately.
+    \deprecated [6.2] Use the other constructor, because \a intValue is no longer stored separately.
 
     Constructs a native gesture event of type \a type originating from \a device.
 
@@ -2809,7 +2836,6 @@ QTabletEvent::~QTabletEvent()
     it is stored in the same variable, such that value() returns the value
     given as \a intValue.
 */
-#if QT_DEPRECATED_SINCE(6, 2)
 QNativeGestureEvent::QNativeGestureEvent(Qt::NativeGestureType type, const QPointingDevice *device,
                                         const QPointF &localPos, const QPointF &scenePos,
                                         const QPointF &globalPos, qreal realValue, quint64 sequenceId,
@@ -2900,6 +2926,7 @@ QNativeGestureEvent::~QNativeGestureEvent() = default;
 /*!
     \fn QPoint QNativeGestureEvent::globalPos() const
     \since 5.2
+    \deprecated [6.0] Use globalPosition().toPoint() instead.
 
     Returns the position of the gesture as a QPointF in screen coordinates
 */
@@ -2907,6 +2934,7 @@ QNativeGestureEvent::~QNativeGestureEvent() = default;
 /*!
     \fn QPoint QNativeGestureEvent::pos() const
     \since 5.2
+    \deprecated [6.0] Use position().toPoint() instead.
 
     Returns the position of the mouse cursor, relative to the widget
     or item that received the event.
@@ -2915,6 +2943,7 @@ QNativeGestureEvent::~QNativeGestureEvent() = default;
 /*!
     \fn QPointF QNativeGestureEvent::localPos() const
     \since 5.2
+    \deprecated [6.0] Use position() instead.
 
     Returns the position of the gesture as a QPointF, relative to the
     widget or item that received the event.
@@ -2923,6 +2952,7 @@ QNativeGestureEvent::~QNativeGestureEvent() = default;
 /*!
     \fn QPointF QNativeGestureEvent::screenPos() const
     \since 5.2
+    \deprecated [6.0] Use globalPosition() instead.
 
     Returns the position of the gesture as a QPointF in screen coordinates.
 */
@@ -2930,6 +2960,7 @@ QNativeGestureEvent::~QNativeGestureEvent() = default;
 /*!
     \fn QPointF QNativeGestureEvent::windowPos() const
     \since 5.2
+    \deprecated [6.0] Use scenePosition() instead.
 
     Returns the position of the gesture as a QPointF, relative to the
     window that received the event.
@@ -3107,24 +3138,28 @@ void QDropEvent::setDropAction(Qt::DropAction action)
 
 /*!
     \fn QPoint QDropEvent::pos() const
+    \deprecated [6.0] Use position().toPoint() instead.
 
     Returns the position where the drop was made.
 */
 
 /*!
     \fn const QPointF& QDropEvent::posF() const
+    \deprecated [6.0] Use position() instead.
 
     Returns the position where the drop was made.
 */
 
 /*!
     \fn Qt::MouseButtons QDropEvent::mouseButtons() const
+    \deprecated [6.0] Use buttons() instead.
 
     Returns the mouse buttons that are pressed..
 */
 
 /*!
     \fn Qt::KeyboardModifiers QDropEvent::keyboardModifiers() const
+    \deprecated [6.0] Use modifiers() instead.
 
     Returns the modifier keys that are pressed.
 */
@@ -4484,6 +4519,8 @@ QWindowStateChangeEvent::~QWindowStateChangeEvent()
 */
 
 /*!
+    \deprecated [6.2] Use another constructor.
+
     Constructs a QTouchEvent with the given \a eventType, \a device,
     \a touchPoints, and current keyboard \a modifiers at the time of the event.
 */
@@ -4502,9 +4539,7 @@ QTouchEvent::QTouchEvent(QEvent::Type eventType,
 }
 
 /*!
-    \deprecated
-    Try to use another constructor, because \a touchPointStates
-    can be calculated from the given \a touchPoints.
+    \deprecated [6.0] Use another constructor.
 
     Constructs a QTouchEvent with the given \a eventType, \a device, and
     \a touchPoints. The \a touchPointStates and \a modifiers are the current
@@ -4567,8 +4602,7 @@ bool QTouchEvent::isEndEvent() const
 */
 
 /*! \fn const QList<QEventPoint> &QTouchEvent::touchPoints() const
-    \deprecated
-    Deprecated since Qt 6.0. Use points() instead.
+    \deprecated [6.0] Use points() instead.
 
     Returns a reference to the list of touch points contained in the touch event.
 
diff --git a/src/gui/kernel/qeventpoint.cpp b/src/gui/kernel/qeventpoint.cpp
index 0c8428286a..249569a853 100644
--- a/src/gui/kernel/qeventpoint.cpp
+++ b/src/gui/kernel/qeventpoint.cpp
@@ -142,8 +142,7 @@ bool QEventPoint::operator==(const QEventPoint &other) const noexcept
 QEventPoint::~QEventPoint() = default;
 
 /*! \fn QPointF QEventPoint::pos() const
-    \deprecated
-    Deprecated since Qt 6.0. Use position() instead.
+    \deprecated [6.0] Use position() instead.
 
     Returns the position of this point, relative to the widget
     or item that received the event.
@@ -443,10 +442,8 @@ bool QEventPoint::isAccepted() const
 
 
 /*!
-    \deprecated
     \fn QPointF QEventPoint::normalizedPos() const
-
-    Deprecated since Qt 6.0. Use normalizedPosition() instead.
+    \deprecated [6.0] Use normalizedPosition() instead.
 */
 
 /*!
@@ -470,8 +467,7 @@ QPointF QEventPoint::normalizedPosition() const
 }
 
 /*!
-    \deprecated
-    Deprecated since Qt 6.0. Use globalPressPosition() instead.
+    \deprecated [6.0] Use globalPressPosition() instead.
 
     Returns the normalized press position of this point.
 */
@@ -487,8 +483,7 @@ QPointF QEventPoint::startNormalizedPos() const
 }
 
 /*!
-    \deprecated
-    Deprecated since Qt 6.0. Use globalLastPosition() instead.
+    \deprecated [6.0] Use globalLastPosition() instead.
 
     Returns the normalized position of this point from the previous press or
     move event.
@@ -496,7 +491,7 @@ QPointF QEventPoint::startNormalizedPos() const
     The coordinates are normalized to QInputDevice::availableVirtualGeometry(),
     i.e. \c (0, 0) is the top-left corner and \c (1, 1) is the bottom-right corner.
 
-    \sa normalizedPos(), startNormalizedPos()
+    \sa normalizedPosition(), globalPressPosition()
 */
 QPointF QEventPoint::lastNormalizedPos() const
 {
diff --git a/src/gui/kernel/qguiapplication.cpp b/src/gui/kernel/qguiapplication.cpp
index c93e483438..e7bd2b8358 100644
--- a/src/gui/kernel/qguiapplication.cpp
+++ b/src/gui/kernel/qguiapplication.cpp
@@ -3288,7 +3288,7 @@ QClipboard * QGuiApplication::clipboard()
 /*!
     \since 5.4
     \fn void QGuiApplication::paletteChanged(const QPalette &palette)
-    \deprecated
+    \deprecated [6.0] Handle QEvent::ApplicationPaletteChange instead.
 
     This signal is emitted when the \a palette of the application changes. Use
     QEvent::ApplicationPaletteChanged instead.
@@ -3399,7 +3399,7 @@ void QGuiApplicationPrivate::applyWindowGeometrySpecificationTo(QWindow *window)
 /*!
     \since 5.11
     \fn void QGuiApplication::fontChanged(const QFont &font)
-    \deprecated
+    \deprecated [6.0] Handle QEvent::ApplicationFontChange instead.
 
     This signal is emitted when the \a font of the application changes. Use
     QEvent::ApplicationFontChanged instead.
diff --git a/src/gui/kernel/qpointingdevice.cpp b/src/gui/kernel/qpointingdevice.cpp
index 2a09ee3ca9..3675cec2dd 100644
--- a/src/gui/kernel/qpointingdevice.cpp
+++ b/src/gui/kernel/qpointingdevice.cpp
@@ -179,7 +179,7 @@ QPointingDevice::QPointingDevice(QPointingDevicePrivate &d, QObject *parent)
 
 /*!
     \internal
-    \deprecated Please use the constructor rather than setters.
+    \deprecated [6.0] Please use the constructor rather than setters.
 
     Sets the device type \a devType and infers the pointer type.
 */
@@ -210,7 +210,7 @@ void QPointingDevice::setType(DeviceType devType)
 
 /*!
     \internal
-    \deprecated Please use the constructor rather than setters.
+    \deprecated [6.0] Please use the constructor rather than setters.
 */
 void QPointingDevice::setCapabilities(QInputDevice::Capabilities caps)
 {
@@ -220,7 +220,7 @@ void QPointingDevice::setCapabilities(QInputDevice::Capabilities caps)
 
 /*!
     \internal
-    \deprecated Please use the constructor rather than setters.
+    \deprecated [6.0] Please use the constructor rather than setters.
 */
 void QPointingDevice::setMaximumTouchPoints(int c)
 {