doc: Clarify that DelegateModel is a kind of proxy model

It was not quite clear in the GridView DnD example that the ListModel
doesn't get reordered, so if new ListElements are inserted after reordering
the DelegateModel by DnD, predicting the position where new delegates will
appear becomes a bit of a riddle.

Also:
- the QQmlDelegateModelAttached::model is a model, not an int
- disambiguate the properties that have the same names in
  QQmlDelegateModel and QQmlDelegateModelAttached, using \keyword
  for linking.

Task-number: QTBUG-34891
Change-Id: I485fd632f67d607652428b4e3c9ca528e57f7348
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

2 files changed, 15 insertions, 8 deletions

diff --git a/examples/quick/draganddrop/doc/src/draganddrop.qdoc b/examples/quick/draganddrop/doc/src/draganddrop.qdoc
index b740582cc4..754fa8f8cb 100644
--- a/examples/quick/draganddrop/doc/src/draganddrop.qdoc
+++ b/examples/quick/draganddrop/doc/src/draganddrop.qdoc
@@ -57,8 +57,9 @@
 
     \section1 GridView Example
 
-    The \e {GridView Example} adds drag and drop to a \l GridView, allowing you to reorder the
-    list. It also uses a \l DelegateModel to move a delegate item to the
+    The \e {GridView Example} adds drag and drop to a \l GridView, allowing you
+    to visually reorder the delegates without changing the underlying
+    \l ListModel. It uses a \l DelegateModel to move a delegate item to the
     position of another item it is dragged over.
 
     \snippet draganddrop/views/gridview.qml 0
diff --git a/src/qml/types/qqmldelegatemodel.cpp b/src/qml/types/qqmldelegatemodel.cpp
index 53e3f65553..fa7ce946fb 100644
--- a/src/qml/types/qqmldelegatemodel.cpp
+++ b/src/qml/types/qqmldelegatemodel.cpp
@@ -353,6 +353,7 @@ void QQmlDelegateModel::componentComplete()
     \l{QtQuick.XmlListModel::XmlListModel}{XmlListModel}.
 
     \sa {qml-data-models}{Data Models}
+    \keyword dm-model-property
 */
 QVariant QQmlDelegateModel::model() const
 {
@@ -493,11 +494,10 @@ void QQmlDelegateModel::setDelegate(QQmlComponent *delegate)
     \c view.qml:
     \snippet delegatemodel/delegatemodel_rootindex/view.qml 0
 
-    If the \l model is a QAbstractItemModel subclass, the delegate can also
-    reference a \c hasModelChildren property (optionally qualified by a
-    \e model. prefix) that indicates whether the delegate's model item has
-    any child nodes.
-
+    If the \l {dm-model-property}{model} is a QAbstractItemModel subclass,
+    the delegate can also reference a \c hasModelChildren property (optionally
+    qualified by a \e model. prefix) that indicates whether the delegate's
+    model item has any child nodes.
 
     \sa modelIndex(), parentModelIndex()
 */
@@ -699,6 +699,7 @@ QQmlDelegateModelGroup *QQmlDelegateModelPrivate::group_at(
     The following example illustrates using groups to select items in a model.
 
     \snippet delegatemodel/delegatemodelgroup.qml 0
+    \keyword dm-groups-property
 */
 
 QQmlListProperty<QQmlDelegateModelGroup> QQmlDelegateModel::groups()
@@ -2274,7 +2275,7 @@ void QQmlDelegateModelAttached::resetCurrentIndex()
 }
 
 /*!
-    \qmlattachedproperty int QtQml.Models::DelegateModel::model
+    \qmlattachedproperty model QtQml.Models::DelegateModel::model
 
     This attached property holds the data model this delegate instance belongs to.
 
@@ -3094,6 +3095,11 @@ void QQmlDelegateModelGroup::setGroups(QQmlV4Function *args)
     \qmlmethod QtQml.Models::DelegateModelGroup::move(var from, var to, int count)
 
     Moves \a count at \a from in a group \a to a new position.
+
+    \note The DelegateModel acts as a proxy model: it holds the delegates in a
+    different order than the \l{dm-model-property}{underlying model} has them.
+    Any subsequent changes to the underlying model will not undo whatever
+    reordering you have done via this function.
 */
 
 void QQmlDelegateModelGroup::move(QQmlV4Function *args)