From 900786226404c915f3b2eb2840a1f3eb391db69b Mon Sep 17 00:00:00 2001
From: Mitch Curtis <mitch.curtis@qt.io>
Date: Fri, 26 Oct 2018 14:46:48 +0200
Subject: Doc: improve qmlRegisterInterface() documentation

Change-Id: I5e8b63a287c65baf1eb53957cc5a9585176db284
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>
---
 src/qml/doc/src/qmlfunctions.qdoc | 33 ++++++++++++++++++++++++++++-----
 src/qml/qml/qqmlmetatype.cpp      |  3 +++
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index 62c0f5d81b..969dd51433 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -356,13 +356,36 @@
 */
 
 /*!
-  \fn int qmlRegisterInterface(const char *typeName)
-  \relates QQmlEngine
+    \fn int qmlRegisterInterface(const char *typeName)
+    \relates QQmlEngine
 
-  This template function registers the C++ type in the QML system
-  under the name \a typeName.
+    This template function registers the C++ type in the QML system
+    under the name \a typeName.
 
-  Returns the QML type id.
+    Types registered as an interface with the engine should also
+    declare themselves as an interface with the
+    \l {The Meta-Object System}{meta object system}. For example:
+
+    \code
+    struct FooInterface
+    {
+    public:
+        virtual ~FooInterface();
+        virtual void doSomething() = 0;
+    };
+
+    Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
+    \endcode
+
+    When registered with the QML engine in this way, they can be used as
+    property types:
+
+    Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)
+
+    When you assign a \l QObject sub-class to this property, the QML engine does
+    the interface cast to \c FooInterface* automatically.
+
+    Returns the QML type id.
 */
 
 /*!
diff --git a/src/qml/qml/qqmlmetatype.cpp b/src/qml/qml/qqmlmetatype.cpp
index ba8d5831ad..11806a89a0 100644
--- a/src/qml/qml/qqmlmetatype.cpp
+++ b/src/qml/qml/qqmlmetatype.cpp
@@ -2244,6 +2244,9 @@ QQmlMetaType::TypeCategory QQmlMetaType::typeCategory(int userType)
         return Unknown;
 }
 
+/*!
+    See qmlRegisterInterface() for information about when this will return true.
+*/
 bool QQmlMetaType::isInterface(int userType)
 {
     QMutexLocker lock(metaTypeDataLock());
-- 
cgit v1.2.3