Add templated module api registration function

This commit adds a templated module api registration function which
allows clients to provide type information at registration time.
We use this typeinformation in V4 if available, in order to allow
module APIs to be used in v4 bindings.

This commit also clarifies the ownership semantics of QObject module
apis, and updates some documentation references which were missed
during the rename of Declarative to Qml.

Task-number: QTBUG-24894
Change-Id: Iebb61ca8d8eacbb15218549eab715e22f52a1474
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

1 files changed, 20 insertions, 5 deletions

diff --git a/doc/src/qml/qtdeclarative.qdoc b/doc/src/qml/qtdeclarative.qdoc
index 20d1c40d66..48cc898458 100644
--- a/doc/src/qml/qtdeclarative.qdoc
+++ b/doc/src/qml/qtdeclarative.qdoc
@@ -27,10 +27,10 @@
 
 /*!
   \module QtQml
-  \title Qt Declarative Module
+  \title Qt Qml Module
   \ingroup modules
 
-  \brief The Qt Declarative module provides a declarative framework
+  \brief The Qt Qml module provides a declarative framework
   for building highly dynamic, custom user interfaces.
 
   To include the definitions of the module's classes, use the
@@ -44,10 +44,11 @@
   .pro file:
 
   \code
-  QT += declarative
+  QT += qml
   \endcode
 
-  For more information on the Qt Declarative module, see the
+  For more information on the Qt Qml module (including the visual
+  elements which are implemented on top of the Qt Qml module) see the
   \l{Qt Quick} documentation.
 */
 
@@ -278,7 +279,16 @@
   */
 
 /*!
+   \internal
    \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *))
+   \deprecated
+
+   Any uses of a module API in a binding where that module API was registered with this
+   function instead of the template version will result in suboptimal binding generation.
+ */
+
+/*!
+   \fn template<typename T> int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *))
    \relates QQmlEngine
 
    This function may be used to register a module API provider \a callback in a particular \a uri
@@ -289,13 +299,18 @@
 
    A module API may be either a QObject or a QJSValue.  Only one module API provider
    may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor).
-   This function should be used to register a module API provider function which returns a QObject as a module API.
+   This function should be used to register a module API provider function which returns a QObject
+   of the given type T as a module API.
 
    A QObject module API must be imported with a qualifier, and that qualifier may be used as
    the target in a \l Connections element or otherwise used as any other element id would.
    One exception to this is that a QObject module API property may not be aliased (because the
    module API qualifier does not identify an object within the same component as any other item).
 
+   \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML
+   engine.  For this reason, the module API provider function should \b{not} be implemented as a
+   singleton factory.
+
    Usage:
    \code
    // first, define your QObject which provides the functionality.