4 files changed, 77 insertions, 2 deletions

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc
index 7fbc8c4d..211abedc 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc
@@ -48,6 +48,78 @@
     \generatelist {qmltypesbymodule QtQuick.Controls}
     \noautolist
 
+    \section1 Using Qt Quick Controls types in property declarations
+
+    As mentioned in \l {Qt Quick Templates 2 QML Types}, each type in Qt Quick
+    Controls is backed by a C++ "template" type. These types are \l {Qt Quick
+    Templates 2}{non-visual implementations of controls' logic and behavior}.
+
+    For example, the \l Menu type's API and behavior is defined by the C++
+    type in Qt Quick Templates. Each \l {Definition of a Style}{style} that
+    wants to provide a Menu must have a Menu.qml available, and the root
+    item in that file must be the Menu from Qt Quick Templates. When you
+    import QtQuick.Controls and create a Menu in QML, the type you get is
+    actually the QML Menu defined by the style's Menu.qml.
+
+    In order to use a control as the type in a property declaration, you should
+    use the corresponding type from Qt Quick Templates. For example, suppose
+    you had a \c PopupOpener component, which was a Button that opened a
+    Popup:
+
+    \qml
+    // PopupButton.qml
+    import QtQuick.Controls
+
+    Button {
+        required property Popup popup
+
+        onClicked: popup.open()
+    }
+
+    // main.qml
+    PopupButton {
+        popup: saveChangesDialog
+    }
+
+    Dialog {
+        id: saveChangesDialog
+
+        // ...
+    }
+    \endqml
+
+    Running this code will result in an error:
+
+    \badcode
+    Unable to assign Dialog_QMLTYPE to Popup_QMLTYPE
+    \endcode
+
+    This is because of the inheritance hierarchy:
+
+    \badcode
+    Popup (C++ type in QtQuick.Templates)
+    │   └── Popup (QML type in QtQuick.Controls)
+    └── Dialog (C++ type in QtQuick.Templates)
+        └── Dialog (QML type in QtQuick.Controls)
+    \endcode
+
+    Dialog from \c QtQuick.Controls does not derive from the Popup from
+    \c QtQuick.Controls, but from \c QtQuick.Templates.
+
+    Instead, use the Popup from Qt Quick Templates as the property type:
+
+    \qml
+    // PopupButton.qml
+    import QtQuick.Controls
+    import QtQuick.Templates as T
+
+    Button {
+        required property T.Popup popup
+
+        onClicked: popup.open()
+    }
+    \endqml
+
     For more information on the Qt Quick Controls module, see the
     \l {Qt Quick Controls} module documentation.
 
diff --git a/src/imports/templates/doc/src/qtquicktemplates2-qmltypes.qdoc b/src/imports/templates/doc/src/qtquicktemplates2-qmltypes.qdoc
index fb7809e4..127d14e8 100644
--- a/src/imports/templates/doc/src/qtquicktemplates2-qmltypes.qdoc
+++ b/src/imports/templates/doc/src/qtquicktemplates2-qmltypes.qdoc
@@ -57,6 +57,7 @@
 
     \list
         \li \l {Qt Quick Controls QML Types}
+        \li \l {Using Qt Quick Controls types in property declarations}
     \endlist
 
     \noautolist
diff --git a/src/quicktemplates2/qquickcontrol.cpp b/src/quicktemplates2/qquickcontrol.cpp
index 528dc78a..72d2f794 100644
--- a/src/quicktemplates2/qquickcontrol.cpp
+++ b/src/quicktemplates2/qquickcontrol.cpp
@@ -140,7 +140,8 @@ Q_LOGGING_CATEGORY(lcItemManagement, "qt.quick.controls.control.itemmanagement")
     }
     \endcode
 
-    \sa ApplicationWindow, Container
+    \sa ApplicationWindow, Container, {Using Qt Quick Controls types in
+        property declarations}
 */
 
 const QQuickItemPrivate::ChangeTypes QQuickControlPrivate::ImplicitSizeChanges = QQuickItemPrivate::ImplicitWidth | QQuickItemPrivate::ImplicitHeight | QQuickItemPrivate::Destroyed;
diff --git a/src/quicktemplates2/qquickpopup.cpp b/src/quicktemplates2/qquickpopup.cpp
index d367530a..c3536d2e 100644
--- a/src/quicktemplates2/qquickpopup.cpp
+++ b/src/quicktemplates2/qquickpopup.cpp
@@ -609,7 +609,8 @@ void QQuickPopupPrivate::setBottomMargin(qreal value, bool reset)
     \note Popups can only be centered within their immediate parent or
     the window overlay; trying to center in other items will produce a warning.
 
-    \sa {Popup Positioning}, {Item::}{anchors}
+    \sa {Popup Positioning}, {Item::}{anchors}, {Using Qt Quick Controls types
+        in property declarations}
 */
 QQuickPopupAnchors *QQuickPopupPrivate::getAnchors()
 {