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>

11 files changed, 82 insertions, 50 deletions

diff --git a/src/gui/image/qbitmap.cpp b/src/gui/image/qbitmap.cpp
index 45620e7181..95a7b1f7a0 100644
--- a/src/gui/image/qbitmap.cpp
+++ b/src/gui/image/qbitmap.cpp
@@ -114,19 +114,19 @@ QBitmap::QBitmap()
 
     \sa clear()
 */
-
 QBitmap::QBitmap(int w, int h)
     : QPixmap(QSize(w, h), QPlatformPixmap::BitmapType)
 {
 }
 
 /*!
+    \deprecated [6.0] Use fromPixmap instead.
+
     Constructs a bitmap with the given \a size.  The pixels in the
     bitmap are uninitialized.
 
     \sa clear()
 */
-
 QBitmap::QBitmap(const QSize &size)
     : QPixmap(size, QPlatformPixmap::BitmapType)
 {
@@ -149,7 +149,6 @@ QBitmap::QBitmap(const QSize &size)
 
     \sa QPixmap::isNull(), QImageReader::imageFormat()
 */
-
 QBitmap::QBitmap(const QString& fileName, const char *format)
     : QPixmap(QSize(0, 0), QPlatformPixmap::BitmapType)
 {
@@ -277,7 +276,7 @@ QBitmap QBitmap::fromPixmap(const QPixmap &pixmap)
 
 #if QT_DEPRECATED_SINCE(6, 0)
 /*!
-    \deprecated Use fromPixmap instead.
+    \deprecated [6.0] Use fromPixmap instead.
     Constructs a bitmap that is a copy of the given \a pixmap.
 
     If the pixmap has a depth greater than 1, the resulting bitmap
@@ -285,14 +284,13 @@ QBitmap QBitmap::fromPixmap(const QPixmap &pixmap)
 
     \sa QPixmap::depth(), fromImage(), fromData()
 */
-
 QBitmap::QBitmap(const QPixmap &pixmap)
 {
     *this = QBitmap::fromPixmap(pixmap);
 }
 
 /*!
-    \deprecated Use fromPixmap instead.
+    \deprecated [6.0] Use fromPixmap instead.
     \overload
 
     Assigns the given \a pixmap to this bitmap and returns a reference
@@ -303,7 +301,6 @@ QBitmap::QBitmap(const QPixmap &pixmap)
 
     \sa QPixmap::depth()
  */
-
 QBitmap &QBitmap::operator=(const QPixmap &pixmap)
 {
     *this = QBitmap::fromPixmap(pixmap);
diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp
index af28c8a0ec..deffc7177a 100644
--- a/src/gui/image/qicon.cpp
+++ b/src/gui/image/qicon.cpp
@@ -876,7 +876,7 @@ QPixmap QIcon::pixmap(const QSize &size, qreal devicePixelRatio, Mode mode, Stat
 #if QT_DEPRECATED_SINCE(6, 0)
 /*!
   \since 5.1
-  \deprecated
+  \deprecated [6.0] Use pixmap(size, devicePixelRatio) instead.
 
   Returns a pixmap with the requested \a window \a size, \a mode, and \a
   state, generating one if necessary.
@@ -885,8 +885,6 @@ QPixmap QIcon::pixmap(const QSize &size, qreal devicePixelRatio, Mode mode, Stat
   a high-dpi display the pixmap can be larger. In that case it will have
   a devicePixelRatio larger than 1.
 
-  \deprecated Use the overload which takes qreal devicePixelRatio instead.
-
   \sa  actualSize(), paint()
 */
 
@@ -926,6 +924,7 @@ QSize QIcon::actualSize(const QSize &size, Mode mode, State state) const
 #if QT_DEPRECATED_SINCE(6, 0)
 /*!
   \since 5.1
+  \deprecated [6.0] Use actualSize(size) instead.
 
   Returns the actual size of the icon for the requested \a window  \a size, \a
   mode, and \a state.
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)
 {
diff --git a/src/gui/math3d/qmatrix4x4.cpp b/src/gui/math3d/qmatrix4x4.cpp
index 752b4944d0..dab7013a07 100644
--- a/src/gui/math3d/qmatrix4x4.cpp
+++ b/src/gui/math3d/qmatrix4x4.cpp
@@ -633,7 +633,7 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     \fn QVector3D operator*(const QVector3D& vector, const QMatrix4x4& matrix)
     \relates QMatrix4x4
 
-    \deprecated Convert the QVector3D to a QVector4D first, then multiply.
+    \deprecated [6.1] Convert the QVector3D to a QVector4D first, then multiply.
 
     Returns the result of transforming \a vector according to \a matrix,
     with the matrix applied post-vector. The vector is transformed as a point.
@@ -643,7 +643,7 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     \fn QVector3D operator*(const QMatrix4x4& matrix, const QVector3D& vector)
     \relates QMatrix4x4
 
-    \deprecated Use QMatrix4x4::map() or QMatrix4x4::mapVector() instead.
+    \deprecated [6.1] Use QMatrix4x4::map() or QMatrix4x4::mapVector() instead.
 
     Returns the result of transforming \a vector according to \a matrix,
     with the matrix applied pre-vector. The vector is transformed as a
@@ -696,7 +696,7 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     \fn QPoint operator*(const QMatrix4x4& matrix, const QPoint& point)
     \relates QMatrix4x4
 
-    \deprecated Use QMatrix4x4::map() instead.
+    \deprecated [6.1] Use QMatrix4x4::map() instead.
 
     Returns the result of transforming \a point according to \a matrix,
     with the matrix applied pre-point.
@@ -706,7 +706,7 @@ QMatrix4x4& QMatrix4x4::operator/=(float divisor)
     \fn QPointF operator*(const QMatrix4x4& matrix, const QPointF& point)
     \relates QMatrix4x4
 
-    \deprecated Use QMatrix4x4::map() instead.
+    \deprecated [6.1] Use QMatrix4x4::map() instead.
 
     Returns the result of transforming \a point according to \a matrix,
     with the matrix applied pre-point.
diff --git a/src/gui/text/qfont.cpp b/src/gui/text/qfont.cpp
index b6d7160cd4..eb682388ff 100644
--- a/src/gui/text/qfont.cpp
+++ b/src/gui/text/qfont.cpp
@@ -691,8 +691,10 @@ QFont::QFont()
 {
 }
 
+#if QT_DEPRECATED_SINCE(6, 2)
 /*!
-    \deprecated
+    \deprecated [6.2] Use the overload taking a QStringList instead.
+
     Constructs a font object with the specified \a family, \a
     pointSize, \a weight and \a italic settings.
 
@@ -738,6 +740,7 @@ QFont::QFont(const QString &family, int pointSize, int weight, bool italic)
     d->request.weight = weight;
     d->request.style = italic ? QFont::StyleItalic : QFont::StyleNormal;
 }
+#endif
 
 /*!
      Constructs a font object with the specified \a families, \a
@@ -1183,7 +1186,7 @@ QFont::Weight QFont::weight() const
 
 #if QT_DEPRECATED_SINCE(6, 0)
 /*!
-    \deprecated Use setWeight() instead.
+    \deprecated [6.0] Use setWeight() instead.
 
     Sets the weight of the font to \a legacyWeight using the legacy font
     weight scale of Qt 5 and previous versions.
@@ -1195,7 +1198,7 @@ QFont::Weight QFont::weight() const
 
     \note If styleName() is set, this value may be ignored for font selection.
 
-    \sa setWeight(), weight(), legacyWeight(), QFontInfo
+    \sa setWeight(), weight(), QFontInfo
 */
 void QFont::setLegacyWeight(int legacyWeight)
 {
@@ -1203,7 +1206,7 @@ void QFont::setLegacyWeight(int legacyWeight)
 }
 
 /*!
-    \deprecated Use weight() instead.
+    \deprecated [6.0] Use weight() instead.
 
     Returns the weight of the font converted to the non-standard font
     weight scale used in Qt 5 and earlier versions.
diff --git a/src/gui/text/qfont.h b/src/gui/text/qfont.h
index 87fc08dda9..72c65f6274 100644
--- a/src/gui/text/qfont.h
+++ b/src/gui/text/qfont.h
@@ -167,7 +167,11 @@ public:
     Q_ENUM(ResolveProperties)
 
     QFont();
+
+#if QT_DEPRECATED_SINCE(6, 2)
+    QT_DEPRECATED_VERSION_X_6_2("Pass QStringList{family} or family.split(QLatin1Char(',')) instead of family")
     QFont(const QString &family, int pointSize = -1, int weight = -1, bool italic = false);
+#endif
     explicit QFont(const QStringList &families, int pointSize = -1, int weight = -1, bool italic = false);
     QFont(const QFont &font, const QPaintDevice *pd);
     QFont(const QFont &font);
diff --git a/src/gui/text/qfontdatabase.cpp b/src/gui/text/qfontdatabase.cpp
index 3eb59e0f04..02ac67ce9e 100644
--- a/src/gui/text/qfontdatabase.cpp
+++ b/src/gui/text/qfontdatabase.cpp
@@ -1239,7 +1239,7 @@ QString QFontDatabase::styleString(const QFontInfo &fontInfo)
 
 /*!
     \fn QFontDatabase::QFontDatabase()
-    \deprecated Call the class methods as static functions instead.
+    \deprecated [6.0] Call the class methods as static functions instead.
 
     Creates a font database object.
 */
diff --git a/src/gui/text/qtextformat.cpp b/src/gui/text/qtextformat.cpp
index 0166cd7ad2..caa2eb0f3f 100644
--- a/src/gui/text/qtextformat.cpp
+++ b/src/gui/text/qtextformat.cpp
@@ -1373,7 +1373,7 @@ bool QTextFormat::operator==(const QTextFormat &rhs) const
 
     The font used can be set by supplying a font to the setFont() function, and
     each aspect of its appearance can be adjusted to give the desired effect.
-    setFontFamily() and setFontPointSize() define the font's family (e.g. Times)
+    setFontFamilies() and setFontPointSize() define the font's family (e.g. Times)
     and printed size; setFontWeight() and setFontItalic() provide control over
     the style of the font. setFontUnderline(), setFontOverline(),
     setFontStrikeOut(), and setFontFixedPitch() provide additional effects for
@@ -1457,7 +1457,7 @@ QTextCharFormat::QTextCharFormat(const QTextFormat &fmt)
 
 /*!
     \fn void QTextCharFormat::setFontFamily(const QString &family)
-    \deprecated Use setFontFamilies() instead.
+    \deprecated [6.1] Use setFontFamilies() instead.
 
     Sets the text format's font \a family.
 
@@ -1467,7 +1467,7 @@ QTextCharFormat::QTextCharFormat(const QTextFormat &fmt)
 
 /*!
     \fn QString QTextCharFormat::fontFamily() const
-    \deprecated Use fontFamilies() instead.
+    \deprecated [6.1] Use fontFamilies() instead.
 
     Returns the text format's font family.