diff --git a/src/widgets/widgets/qdockwidget.cpp b/src/widgets/widgets/qdockwidget.cpp
index 50162357559..6675d7a6bd7 100644
--- a/src/widgets/widgets/qdockwidget.cpp
+++ b/src/widgets/widgets/qdockwidget.cpp
@@ -1233,6 +1233,11 @@ void QDockWidgetPrivate::setWindowState(bool floating, bool unplug, const QRect
     on whether it is docked; a docked QDockWidget has no frame and a smaller title
     bar.
 
+    \note On macOS, if the QDockWidget has a native window handle (for example,
+    if winId() is called on it or the child widget), then due to a limitation it will not be
+    possible to drag the dock widget when undocking. Starting the drag will undock
+    the dock widget, but a second drag will be needed to move the dock widget itself.
+
     \sa QMainWindow, {Dock Widgets Example}
 */