1 files changed, 52 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc
index 2bb1fcac61..15e8e4c52c 100644
--- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc
+++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc
@@ -540,6 +540,58 @@ Internally, however, the rectangle can correctly set its \c color
 property and refer to the actual defined property rather than the alias.
 
 
+\section4 Property Aliases and Types
+
+Property aliases cannot have explicit type specifications. The type of a
+property alias is the \e declared type of the property or object it refers to.
+Therefore, if you create an alias to an object referenced via id with extra
+properties declared inline, the extra properties won't be accessible through
+the alias:
+
+\code
+// MyItem.qml
+Item {
+    property alias inner: innerItem
+
+    Item {
+        id: innerItem
+        property int extraProperty
+    }
+}
+\code
+
+You cannot initialize \a inner.extraProperty from outside of this component, as
+inner is only an \a Item:
+
+\code
+// main.qml
+MyItem {
+    inner.extraProperty: 5 // fails
+}
+\code
+
+However, if you extract the inner object into a separate component with a
+dedicated .qml file, you can instantiate that component instead and have all
+its properties available through the alias:
+
+\code
+// MainItem.qml
+Item {
+    // Now you can access inner.extraProperty, as inner is now an ExtraItem
+    property alias inner: innerItem
+
+    ExtraItem {
+        id: innerItem
+    }
+}
+
+// ExtraItem.qml
+Item {
+    property int extraProperty
+}
+\code
+
+
 \section3 Default Properties
 
 An object definition can have a single \e default property. A default property