Document that Q_GADGET classes cannot be used with newQMetaObject()

Task-number: QTBUG-62007
Change-Id: I63d5a57163b36bc8629930e1cda8d5afa1e77d15
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>

2 files changed, 39 insertions, 5 deletions

diff --git a/src/qml/doc/snippets/code/src_script_qjsengine.cpp b/src/qml/doc/snippets/code/src_script_qjsengine.cpp
index 876990fb3f..0310ae042c 100644
--- a/src/qml/doc/snippets/code/src_script_qjsengine.cpp
+++ b/src/qml/doc/snippets/code/src_script_qjsengine.cpp
@@ -114,3 +114,23 @@ engine.globalObject().setProperty("myObject", myScriptQObject);
 
 qDebug() << engine.evaluate("myObject.dynamicProperty").toInt();
 //! [6]
+
+
+//! [7]
+class MyObject : public QObject
+{
+    Q_OBJECT
+
+public:
+    Q_INVOKABLE MyObject() {}
+};
+//! [7]
+
+//! [8]
+QJSValue jsMetaObject = engine.newQMetaObject(&MyObject::staticMetaObject);
+engine.globalObject().setProperty("MyObject", jsMetaObject);
+//! [8]
+
+//! [9]
+engine.evaluate("var myObject = new MyObject()");
+//! [9]
diff --git a/src/qml/jsapi/qjsengine.cpp b/src/qml/jsapi/qjsengine.cpp
index d5b8b295a7..6cab8def4f 100644
--- a/src/qml/jsapi/qjsengine.cpp
+++ b/src/qml/jsapi/qjsengine.cpp
@@ -166,16 +166,30 @@ Q_DECLARE_METATYPE(QList<int>)
   properties of the proxy object. No binding code is needed because it
   is done dynamically using the Qt meta object system.
 
+  \snippet code/src_script_qjsengine.cpp 5
+
   Use newQMetaObject() to wrap a QMetaObject; this gives you a
   "script representation" of a QObject-based class. newQMetaObject()
   returns a proxy script object; enum values of the class are available
   as properties of the proxy object.
 
-  Constructors exposed to the meta-object system ( using Q_INVOKABLE ) can be
+  Constructors exposed to the meta-object system (using Q_INVOKABLE) can be
   called from the script to create a new QObject instance with
-  JavaScriptOwnership.
+  JavaScriptOwnership. For example, given the following class definition:
 
-  \snippet code/src_script_qjsengine.cpp 5
+  \snippet code/src_script_qjsengine.cpp 7
+
+  The \c staticMetaObject for the class can be exposed to JavaScript like so:
+
+  \snippet code/src_script_qjsengine.cpp 8
+
+  Instances of the class can then be created in JavaScript:
+
+  \snippet code/src_script_qjsengine.cpp 9
+
+  \note Currently only classes using the Q_OBJECT macro are supported; it is
+  not possible to expose the \c staticMetaObject of a Q_GADGET class to
+  JavaScript.
 
   \section2 Dynamic QObject Properties
 
@@ -537,7 +551,7 @@ QJSValue QJSEngine::newQObject(QObject *object)
   When called as a constructor, a new instance of the class will be created.
   Only constructors exposed by Q_INVOKABLE will be visible from the script engine.
 
-  \sa newQObject()
+  \sa newQObject(), {QObject Integration}
 */
 
 QJSValue QJSEngine::newQMetaObject(const QMetaObject* metaObject) {
@@ -554,7 +568,7 @@ QJSValue QJSEngine::newQMetaObject(const QMetaObject* metaObject) {
   Creates a JavaScript object that wraps the static QMetaObject associated
   with class \c{T}.
 
-  \sa newQObject()
+  \sa newQObject(), {QObject Integration}
 */