QtQml: Fix documentation on grouped properties

The base properties of grouped properties don't have to be read-only,
but making them read-only is generally a good idea. Also, describe the
dilemma of assigning both, the whole object and individual properties.

Pick-to: 6.11 6.8
Change-Id: I803eb152a350e72d36ef1cc801b99a5c7c453222
Reviewed-by: Sami Shalayel <sami.shalayel@qt.io>
(cherry picked from commit 02adb073a928a2c0db8b5ec19f9401d7700213c7)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 94 insertions, 27 deletions

diff --git a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc
index 7b86dfa59f..d8b1ff2b04 100644
--- a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc
+++ b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc
@@ -212,9 +212,10 @@ be done with care to ensure that performance doesn't suffer.
 
 The presence of a NOTIFY signal does incur a small overhead. There are cases
 where a property's value is set at object construction time, and does not
-subsequently change. The most common case of this is when a type uses \l
-{#Grouped Properties}{Grouped Properties}, and the grouped property object is
-allocated once, and only freed when the object is deleted. In these cases,
+subsequently change. The most common case of this is a read-only property that
+holds a sub-object, typically accessed through
+\l{#Grouped Properties}{grouped property syntax}, where the sub-object is
+allocated once, and only freed when the owner is deleted. In these cases,
 the CONSTANT attribute may be added to the property declaration instead of a
 NOTIFY signal.
 
@@ -327,9 +328,11 @@ Note that the template class type for the QQmlListProperty — in this case,
 \section2 Grouped Properties
 \keyword Integrating QML and C++ - Grouped Properties
 
-Any read-only object-type property is accessible from QML code as a
-\e {grouped property}. This can be used to expose a group of related
-properties that describe a set of attributes for a type.
+Any property whose type has sub-properties of its own can be manipulated using
+the \l{QML Object Attributes#Grouped Properties}{grouped property syntax}, no
+matter whether that type is a value type such as \c font or an object type.
+Grouped properties are useful to expose a group of related properties that
+describe a set of attributes for a type.
 
 For example, suppose the \c Message::author property was of type
 \c MessageAuthor rather than a simple string, with sub-properties
@@ -362,9 +365,8 @@ private:
 \endcode
 
 The \c author property could be written to using the
-\l{qtqml-syntax-objectattributes.html#grouped-properties}{grouped property
-syntax}
-in QML, like this:
+\l{QML Object Attributes#Grouped Properties}{grouped property syntax} in QML,
+like this:
 
 \qml
 Message {
@@ -373,15 +375,62 @@ Message {
 }
 \endqml
 
-A type that is exposed as a grouped property differs from an \l{Properties with
-Object Types}{object-type property} in that the grouped property is read-only,
-and is initialized to a valid value by the parent object at construction. The
-grouped property's sub-properties may be modified from QML but the grouped
-property object itself will never change, whereas an object-type property may be
-assigned a new object value from QML at any time. Thus, the lifetime of a
-grouped property object is controlled strictly by the C++ parent
-implementation, whereas an object-type property can be freely created and
-destroyed through QML code.
+Since \c author is an \l{Properties with Object Types}{object-type property},
+the grouped assignments do not create the \c MessageAuthor object. They are
+written to whatever object \c Message::author() returns. This has a few
+consequences:
+
+\list
+\li The sub-property names are resolved against the \e declared type of the
+    property, here \c MessageAuthor, not against the type of the object that
+    happens to be stored in it at run time. Different instantiations of
+    \c Message could produce \c author objects of different types. The only
+    thing we can rely on when creating the QML component is the declared type.
+\li The object has to exist when the grouped assignments are applied.
+    Otherwise the engine throws an error along the lines of
+    \c {Cannot set properties on author as it is null}. Creating the object in
+    the owner's constructor, as above, is the simplest way to guarantee this,
+    but a getter that creates the object on first access works just as well.
+\li The lifetime of the object is whatever the C++ implementation makes it.
+    Grouped property syntax neither creates nor destroys objects.
+\endlist
+
+Declaring \c author read-only, as in the example above, additionally prevents
+QML code from replacing the \c MessageAuthor object. If \c author had a
+\c WRITE accessor, you could equally well assign a new object to it:
+
+\qml
+Message {
+    author: MessageAuthor {
+        name: "Alexandra"
+        email: "alexandra@mail.com"
+    }
+}
+\endqml
+
+You cannot combine the two forms for the same property in the same
+object definition. Assigning an object to \c author and also writing
+\c author.name in the same \c Message produces an error. You can subvert that
+by having the grouped property in a different scope. However, doing so produces
+confusing results because now you have two \c MessageAuthor objects, the one
+created by the constructor and the one assigned explicitly. Only binding
+evaluation order determines which one the grouped property applies to.
+
+This means that the good practice is:
+
+\list
+\li Keep objects used as grouped properties read-only.
+\li Avoid grouped property syntax if you also manipulate the base property of
+    the group itself.
+\endlist
+
+For a \l {QML Value Types}{value type} property such as \c font, grouped
+assignments require the property to be writable, since the engine reads the
+value, modifies it, and writes it back. The potential confusion is still a
+problem, though. If you re-assign the whole \c font in place and then manipulate
+the \c font.bold property in a different place, binding evaluation order
+determines which one is done first, and what value of \c bold will result from
+it.
 
 
 \section1 Exposing Methods (Including Qt Slots)
diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc
index d6ce92406a..54dee9b779 100644
--- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc
+++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc
@@ -407,27 +407,45 @@ In some cases properties contain a logical group of sub-property attributes.
 These sub-property attributes can be assigned to using either the dot notation
 or group notation.
 
-For example, the \l Text type has a \l{Text::font.family}{font} group property. Below,
-the first \l Text object initializes its \c font values using dot notation,
-while the second uses group notation:
+For example, the \l Text type has a \c font property.
+Below, the first \l Text object initializes its \c font values using
+dot notation, while the second uses group notation:
 
 \code
 Text {
     //dot notation
     font.pixelSize: 12
-    font.b: true
+    font.bold: true
 }
 
 Text {
     //group notation
-    font { pixelSize: 12; b: true }
+    font { pixelSize: 12; bold: true }
 }
 \endcode
 
-Grouped property types are types which have subproperties. If a grouped property
-type is an object type (as opposed to a value type), the property that holds it
-must be read-only. This is to prevent you from replacing the object the
-subproperties belong to.
+Grouped property syntax is available for any property whose type has
+sub-properties of its own. It is a notation, not a separate kind of property:
+whether the property holds a \l{QML Value Types}{value type} like \c font or
+an \l{QML Object Types}{object type} makes no difference to the syntax.
+
+The type of the property does affect what the engine has to do, though:
+
+\list
+\li If the property holds a value type, the engine reads the value, modifies
+    it, and writes it back. The property therefore has to be writable.
+\li If the property holds an object type, the assignments are written to the
+    object that the property currently holds. That object must not be null when
+    the assignments are applied. The property itself may be read-only or
+    writable. Making it read-only is a way to keep QML code from replacing the
+    object the sub-properties belong to, thus avoiding confusion over what
+    object the grouped properties apply to. It is generally a good idea.
+\endlist
+
+Sub-property names are resolved against the property's declared type, not
+against the type of the object it holds at run time. You also cannot use both
+forms for the same property in the same object definition: either assign an
+object to the property, or assign to its sub-properties.
 
 \section3 Property Aliases