diff --git a/src/gui/kernel/qwindow.cpp b/src/gui/kernel/qwindow.cpp
index 5a0fc79f30..39cbf0d734 100644
--- a/src/gui/kernel/qwindow.cpp
+++ b/src/gui/kernel/qwindow.cpp
@@ -1882,6 +1882,10 @@ void QWindow::setFramePosition(const QPoint &point)
     For interactively moving windows, see startSystemMove(). For interactively
     resizing windows, see startSystemResize().
 
+    \note Not all windowing systems support setting or querying top level window positions.
+    On such a system, programmatically moving windows may not have any effect, and artificial
+    values may be returned for the current positions, such as \c QPoint(0, 0).
+
     \sa position(), startSystemMove()
 */
 void QWindow::setPosition(const QPoint &pt)
@@ -1905,6 +1909,10 @@ void QWindow::setPosition(int posx, int posy)
     \fn QPoint QWindow::position() const
     \brief Returns the position of the window on the desktop excluding any window frame
 
+    \note Not all windowing systems support setting or querying top level window positions.
+    On such a system, programmatically moving windows may not have any effect, and artificial
+    values may be returned for the current positions, such as \c QPoint(0, 0).
+
     \sa setPosition()
 */
 
diff --git a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
index 192d05aff7..827f7981ae 100644
--- a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
+++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
@@ -115,6 +115,15 @@
     depends on the result of QWidget::frameGeometry() and the
     capability of the window manager to do proper window placement,
     neither of which can be guaranteed.
+
+    \section2 Wayland Peculiarities
+
+    On Wayland, programmatically setting or getting the position of a top-level window from the
+    client-side is typically not supported. Technically speaking, it depends on the shell
+    interface. For typical desktop compositors, however, the default shell interface will be
+    \c{XDG Shell}, which does not support manual positioning of windows. In such cases, Qt will
+    ignore calls to set the top-level position of a window, and, when queried, the window position
+    will always be returned as QPoint(0, 0).
 */
 
 /*!
diff --git a/src/widgets/kernel/qwidget.cpp b/src/widgets/kernel/qwidget.cpp
index 08acae00c7..cb432c84bc 100644
--- a/src/widgets/kernel/qwidget.cpp
+++ b/src/widgets/kernel/qwidget.cpp
@@ -3547,6 +3547,10 @@ int QWidget::y() const
     See the \l{Window Geometry} documentation for an overview of geometry
     issues with windows.
 
+    \note Not all windowing systems support setting or querying top level window positions.
+    On such a system, programmatically moving windows may not have any effect, and artificial
+    values may be returned for the current positions, such as \c QPoint(0, 0).
+
     \sa frameGeometry, size, x(), y()
 */
 QPoint QWidget::pos() const