diff --git a/src/gui/kernel/qscreen.cpp b/src/gui/kernel/qscreen.cpp
index e6f408875e..1818e19612 100644
--- a/src/gui/kernel/qscreen.cpp
+++ b/src/gui/kernel/qscreen.cpp
@@ -547,6 +547,11 @@ Qt::ScreenOrientation QScreen::orientation() const
 /*!
   \property QScreen::refreshRate
   \brief the approximate vertical refresh rate of the screen in Hz
+
+  \warning Avoid using the screen's refresh rate to drive animations
+  via a timer such as QTimer. Instead use QWindow::requestUpdate().
+
+  \sa QWindow::requestUpdate()
 */
 qreal QScreen::refreshRate() const
 {