From 67c9f735ceb148dba482ca7174b5f3bd8de7892f Mon Sep 17 00:00:00 2001
From: Mitch Curtis <mitch.curtis@qt.io>
Date: Tue, 3 Apr 2018 16:07:50 +0200
Subject: Improve documentation for qmlRegisterType<Foo>()

Explain when it should be used.

Task-number: QTBUG-67332
Change-Id: I759a192778a0370831f44b871e58c5ee49d3fe3c
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
---
 src/qml/doc/src/qmlfunctions.qdoc | 68 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

(limited to 'src/qml/doc/src/qmlfunctions.qdoc')

diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index 82d85a1472..34dce8f4da 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -282,6 +282,74 @@
   system. Instances of this type cannot be created from the QML
   system.
 
+  This function should be used when the type will not be referenced by name.
+  Specifically, it has to be used for C++ types that are used as the left-hand
+  side of a property binding.
+
+  For example, consider the following two classes:
+
+    \code
+    class Bar : public QObject
+    {
+        Q_OBJECT
+        Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)
+
+    public:
+        Bar() {}
+
+        QString baz() const { return mBaz; }
+
+        void setBaz(const QString &baz)
+        {
+            if (baz == mBaz)
+                return;
+
+            mBaz = baz;
+            emit bazChanged();
+        }
+
+    signals:
+        void bazChanged();
+
+    private:
+        QString mBaz;
+    };
+
+    class Foo : public QObject
+    {
+        Q_OBJECT
+        Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)
+
+    public:
+        Foo() {}
+
+        Bar *bar() { return &mBar; }
+
+    private:
+        Bar mBar;
+    };
+    \endcode
+
+  In QML, we assign a string to the \c baz property of \c bar:
+
+    \code
+    Foo {
+        bar.baz: "abc"
+        Component.onCompleted: print(bar.baz)
+    }
+    \endcode
+
+  For the QML engine to know that the \c Bar type has a \c baz property,
+  we have to make \c Bar known:
+
+    \code
+    qmlRegisterType<Foo>("App", 1, 0, "Foo");
+    qmlRegisterType<Bar>();
+    \code
+
+  As the \c Foo type is instantiated in QML, it must be registered
+  with the version of \l qmlRegisterType() that takes an import URI.
+
   Returns the QML type id.
 
   \sa {Choosing the Correct Integration Method Between C++ and QML}
-- 
cgit v1.2.3