Add documentation for the QtWebChannel module.

Please proof-read it and tell me what needs to be improved. I assume
most people will probably not use the QWebChannel directly. Rather, they
will only consume its features indirectly through the integration in
QtWebKit/QtWebEngine. Thus the documentation here is for QWebChannel as
a library. User-end documentation should be added to QtWebKit, I think.

Change-Id: I259c204e24331271b8dc74ea11695988234a79d3
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

4 files changed, 263 insertions, 0 deletions

diff --git a/src/webchannel/doc/qtwebchannel.qdocconf b/src/webchannel/doc/qtwebchannel.qdocconf
new file mode 100644
index 0000000..e2ed336
--- /dev/null
+++ b/src/webchannel/doc/qtwebchannel.qdocconf
@@ -0,0 +1,56 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+
+project                                             = QtWebChannel
+description                                         = Qt WebChannel Reference Documentation
+version                                             = $QT_VERSION
+
+examplesinstallpath                                 = webchannel
+
+qhp.projects                                        = QtWebChannel
+
+qhp.QtWebChannel.file                               = qtwebchannel.qhp
+qhp.QtWebChannel.namespace                          = org.qt-project.qtwebchannel.$QT_VERSION_TAG
+qhp.QtWebChannel.virtualFolder                      = qtwebchannel
+qhp.QtWebChannel.indexTitle                         = Qt WebChannel
+qhp.QtWebChannel.indexRoot                          =
+
+qhp.QtWebChannel.filterAttributes                   = qtwebchannel $QT_VERSION qtrefdoc
+qhp.QtWebChannel.customFilters.Qt.name              = QtWebChannel $QT_VERSION
+qhp.QtWebChannel.customFilters.Qt.filterAttributes  = qtwebchannel $QT_VERSION
+
+qhp.QtWebChannel.subprojects                        = classes qml examples javascript
+
+qhp.QtWebChannel.subprojects.classes.title          = C++ Classes
+qhp.QtWebChannel.subprojects.classes.indexTitle     = Qt WebChannel C++ Classes
+qhp.QtWebChannel.subprojects.classes.selectors      = class fake:headerfile
+qhp.QtWebChannel.subprojects.classes.sortPages      = true
+
+qhp.QtWebChannel.subprojects.qml.title              = QML Types
+qhp.QtWebChannel.subprojects.qml.indexTitle         = Qt WebChannel QML Types
+qhp.QtWebChannel.subprojects.qml.selectors          = qmlclass
+qhp.QtWebChannel.subprojects.qml.sortPages          = true
+
+qhp.QtWebChannel.subprojects.examples.title         = Examples
+qhp.QtWebChannel.subprojects.examples.indexTitle    = Qt WebChannel Examples
+qhp.QtWebChannel.subprojects.examples.selectors     = fake:example
+qhp.QtWebChannel.subprojects.examples.sortPages     = true
+
+qhp.QtWebChannel.subprojects.javascript.title         = JavaScript API
+qhp.QtWebChannel.subprojects.javascript.indexTitle    = Qt WebChannel JavaScript API
+
+tagfile                                             = ../../../doc/qtwebchannel/qtwebchannel.tags
+
+depends                                             += qtcore qtquick qtqml qmake
+
+headerdirs                                          += .. \
+                                                       ../../imports
+
+sourcedirs                                          += .. \
+                                                       ../../imports
+
+
+exampledirs                                         += ../../../examples/webchannel
+
+navigation.landingpage                              = "Qt WebChannel"
+navigation.cppclassespage                           = "Qt WebChannel C++ Classes"
+navigation.qmltypespage                             = "Qt WebChannel QML Types"
diff --git a/src/webchannel/doc/src/index.qdoc b/src/webchannel/doc/src/index.qdoc
new file mode 100644
index 0000000..635c8bd
--- /dev/null
+++ b/src/webchannel/doc/src/index.qdoc
@@ -0,0 +1,47 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff <milian.wolff@kdab.com>
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtwebchannel-index.html
+    \since 5.4
+    \title Qt WebChannel
+    \brief Bridges the gap between C++/QML and HTML/JavaScript.
+
+    The Qt WebChannel module provides a library for seamless integration of C++/QML applications
+    with HTML/JavaScript clients. Any QObject can be published to remote clients, where its public
+    API becomes available.
+
+    \section1 Related Information
+
+    For more information on how to use this module, please refer to the following pages:
+
+    \list
+    \li \l{Qt WebChannel C++ Classes} explains QWebChannel C++ API.
+    \li \l{Qt WebChannel QML Types} explains the WebChannel QML API.
+    \li The \l{Qt WebChannel Examples} show how use the API in practice.
+    \endlist
+*/
diff --git a/src/webchannel/doc/src/javascript.qdoc b/src/webchannel/doc/src/javascript.qdoc
new file mode 100644
index 0000000..36bc4ab
--- /dev/null
+++ b/src/webchannel/doc/src/javascript.qdoc
@@ -0,0 +1,100 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff <milian.wolff@kdab.com>
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \title Qt WebChannel JavaScript API
+    \page qtwebchannel-javascript.html
+
+    \brief This page explains how to use the JavaScript QWebChannel API in HTML clients.
+
+    \section1 Setup
+
+    To communicate with a QWebChannel or WebChannel, any HTML client must use and setup the
+    JavaScript API provided by \c qwebchannel.js. For HTML clients run inside QtWebKit, you
+    can load the file via \c qrc:///qtwebchannel/qwebchannel.js. For external clients you will
+    need to copy the file to your webserver. Then instantiate a QWebChannel object and pass
+    it a transport object and a callback function, which will be invoked once the
+    initialization of the channel finished and published objects become available.
+
+    The transport object implements a minimal message passing interface. It should be an object
+    with a \c send() function, which takes a stringified JSON message and transmits it to the
+    server-side QWebChannelAbstractTransport object. Furthermore, its \c onmessage property should
+    be called when a message from the server was received. This interface is implemented internally
+    by the QtWebKit navigator.qtWebChannelTransport object. Alternatively, you can also use a
+    WebSocket, which also implements this interface.
+
+    Note that the JavaScript QWebChannel object should be constructed once the transport object is
+    fully operational. In case of a WebSocket, that means you should create the QWebChannel in the
+    socket's \c onopen handler. Take a look at the \l{Standalone Example} to see how this is done.
+
+    \section1 Interacting with QObjects
+
+    Once the callback passed to the QWebChannel object is invoked, the channel has finished
+    initialization and all published objects are accessible to the HTML client via the \c channel.objects
+    property. Thus, assuming an object was published with the identifier "foo", then we can interact with it
+    as shown in the example below. Note that all communication between the HTML client and
+    the QML/C++ server is asynchronous. Properties are cached on the HTML side. Furthermore
+    keep in mind that only QML/C++ data types which can be converted to JSON will be (de-)serialized
+    properly and thus accessible to HTML clients.
+
+    \code
+new QWebChannel(yourTransport, function(channel) {
+
+    // Connect to a signal:
+    channel.objects.foo.mySignal.connect(function() {
+        // This callback will be invoked whenever the signal is emitted on the C++/QML side.
+        console.log(arguments);
+    });
+
+    // To make the object known globally, assign it to the window object, i.e.:
+    window.foo = channel.objects.foo;
+
+    // Invoke a method:
+    foo.myMethod(arg1, arg2, function(returnValue) {
+        // This callback will be invoked when myMethod has a return value. Keep in mind that
+        // the communication is asynchronous, hence the need for this callback.
+        console.log(returnValue);
+    });
+
+    // Read a property value, which is cached on the client side:
+    console.log(foo.myProperty);
+
+    // Writing a property will instantly update the client side cache.
+    // The remote end will be notified about the change asynchronously
+    foo.myProperty = "Hello World!";
+
+    // To get notified about remote property changes,
+    // simply connect to the corresponding notify signal:
+    foo.onMyPropertyChanged.connect(function(newValue) {
+        console.log(newValue);
+    });
+
+    // One can also access enums that are marked with Q_ENUM:
+    console.log(foo.MyEnum.MyEnumerator);
+});
+    \endcode
+*/
diff --git a/src/webchannel/doc/src/module.qdoc b/src/webchannel/doc/src/module.qdoc
new file mode 100644
index 0000000..345485e
--- /dev/null
+++ b/src/webchannel/doc/src/module.qdoc
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff <milian.wolff@kdab.com>
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \module QtWebChannel
+    \title Qt WebChannel C++ Classes
+    \ingroup modules
+    \qtvariable webchannel
+    \since 5.4
+    \brief List of C++ classes that provide the QtWebChannel functionality.
+
+    To use these classes in your application, use the following include
+    statement:
+
+    \code
+    #include <QtWebChannel/QtWebChannel>
+    \endcode
+
+    To link against the module, add this line to your \l qmake \c .pro file:
+
+    \code
+    QT += webchannel
+    \endcode
+*/
+
+/*!
+    \qmlmodule QtWebChannel 1.0
+    \title Qt WebChannel QML Types
+    \since 5.4
+    \brief List of QML types that provide WebChannel functionality.
+
+    The QML types are accessed by using:
+    \badcode
+    import QtWebChannel 1.0
+    \endcode
+*/