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>

13 files changed, 161 insertions, 5 deletions

diff --git a/examples/examples.pro b/examples/examples.pro
index 63677f5..1cb6c9f 100644
--- a/examples/examples.pro
+++ b/examples/examples.pro
@@ -1,5 +1,3 @@
 TEMPLATE = subdirs
 
-qtHaveModule(widgets):qtHaveModule(websockets) {
-    SUBDIRS += standalone
-}
+SUBDIRS += qwebchannel
diff --git a/examples/qwebchannel/doc/examples.qdoc b/examples/qwebchannel/doc/examples.qdoc
new file mode 100644
index 0000000..613d760
--- /dev/null
+++ b/examples/qwebchannel/doc/examples.qdoc
@@ -0,0 +1,49 @@
+/****************************************************************************
+**
+** 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 QtWebChannel module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Digia gives you certain additional
+** rights.  These rights are described in the Digia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \title Qt WebChannel Examples
+    \group qtwebchannel-examples
+    \brief List of Qt WebChannel examples.
+
+    The examples show how to use the QWebChannel C++ and WebChannel QML API.
+
+*/
diff --git a/examples/qwebchannel/doc/standalone-screenshot.png b/examples/qwebchannel/doc/standalone-screenshot.png
new file mode 100644
index 0000000..3c55e19
--- /dev/null
+++ b/examples/qwebchannel/doc/standalone-screenshot.png
diff --git a/examples/qwebchannel/doc/standalone.qdoc b/examples/qwebchannel/doc/standalone.qdoc
new file mode 100644
index 0000000..1d81dad
--- /dev/null
+++ b/examples/qwebchannel/doc/standalone.qdoc
@@ -0,0 +1,64 @@
+/****************************************************************************
+**
+** 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 QtWebChannel module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Digia gives you certain additional
+** rights.  These rights are described in the Digia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example standalone
+    \title Standalone Example
+    \ingroup qtwebchannel-examples
+    \image standalone-screenshot.png
+    \brief Shows how to use the QWebChannel C++ API to communicate with an external client.
+
+    The standalone example is a simple chat between a pure C++/Qt application and a remote HTML
+    client running in your default browser.
+
+    The C++ app sets up a QWebChannel and publishes a Dialog object over it.
+    For the remote client side, \c index.html is opened. Both show a dialog with the list of
+    received messages and an input box to send messages to the other end.
+
+    The Dialog emits the Dialog::sendText() signal when the user sents a message. The signal
+    automatically gets propagated to the HTML client. When the user enters a message on the HTML
+    side, Dialog::receiveText() is called.
+
+    All communication between the HTML client and the C++/Qt server is done over a WebSocket.
+    The C++ side instantiates a QWebSocketServer and wraps incoming QWebSocket connections
+    in WebSocketTransport objects, which implement QWebChannelAbstractTransport. These objects are
+    then connected to the QWebChannel instance.
+*/
diff --git a/examples/qwebchannel/qwebchannel.pro b/examples/qwebchannel/qwebchannel.pro
new file mode 100644
index 0000000..63677f5
--- /dev/null
+++ b/examples/qwebchannel/qwebchannel.pro
@@ -0,0 +1,5 @@
+TEMPLATE = subdirs
+
+qtHaveModule(widgets):qtHaveModule(websockets) {
+    SUBDIRS += standalone
+}
diff --git a/examples/standalone/dialog.ui b/examples/qwebchannel/standalone/dialog.ui
index 056a3f5..056a3f5 100644
--- a/examples/standalone/dialog.ui
+++ b/examples/qwebchannel/standalone/dialog.ui
diff --git a/examples/standalone/index.html b/examples/qwebchannel/standalone/index.html
index 3cce3ec..3cce3ec 100644
--- a/examples/standalone/index.html
+++ b/examples/qwebchannel/standalone/index.html
diff --git a/examples/standalone/main.cpp b/examples/qwebchannel/standalone/main.cpp
index f407da6..cc22ed3 100644
--- a/examples/standalone/main.cpp
+++ b/examples/qwebchannel/standalone/main.cpp
@@ -55,6 +55,9 @@
 
 #include "ui_dialog.h"
 
+/*!
+    An instance of this class gets published over the WebChannel and is then accessible to HTML clients.
+*/
 class Dialog : public QObject
 {
     Q_OBJECT
@@ -75,15 +78,24 @@ public:
     }
 
 signals:
+    /*!
+        This signal is emitted from the C++ side and the text displayed on the HTML client side.
+    */
     void sendText(const QString &text);
 
 public slots:
+    /*!
+        This slot is invoked from the HTML client side and the text displayed on the server side.
+    */
     void receiveText(const QString &text)
     {
         displayMessage(tr("Received message: %1").arg(text));
     }
 
 private slots:
+    /*!
+        Note that this slot is private and thus not accessible to HTML clients.
+    */
     void clicked()
     {
         const QString text = ui.input->text();
@@ -107,21 +119,26 @@ int main(int argc, char** argv)
 {
     QApplication app(argc, argv);
 
-    QWebChannel channel;
+    // setup the QWebSocketServer
     QWebSocketServer server(QStringLiteral("QWebChannel Standalone Example Server"), QWebSocketServer::NonSecureMode);
     if (!server.listen(QHostAddress::LocalHost)) {
         qFatal("Failed to open web socket server.");
         return 1;
     }
 
+    // wrap WebSocket clients in QWebChannelAbstractTransport objects
     WebSocketClientWrapper clientWrapper(&server);
+
+    // setup the channel
+    QWebChannel channel;
     QObject::connect(&clientWrapper, &WebSocketClientWrapper::clientConnected,
                      &channel, &QWebChannel::connectTo);
 
+    // setup the dialog and publish it to the QWebChannel
     Dialog dialog;
-
     channel.registerObject(QStringLiteral("dialog"), &dialog);
 
+    // open a browser window with the client HTML page
     QUrl url = QUrl::fromLocalFile(SOURCE_DIR "/index.html");
     url.setQuery(QStringLiteral("webChannelBaseUrl=") + server.serverUrl().toString());
     QDesktopServices::openUrl(url);
diff --git a/examples/standalone/standalone.pro b/examples/qwebchannel/standalone/standalone.pro
index 37b6de3..37b6de3 100644
--- a/examples/standalone/standalone.pro
+++ b/examples/qwebchannel/standalone/standalone.pro
diff --git a/examples/standalone/websocketclientwrapper.cpp b/examples/qwebchannel/standalone/websocketclientwrapper.cpp
index 219050d..0e776e1 100644
--- a/examples/standalone/websocketclientwrapper.cpp
+++ b/examples/qwebchannel/standalone/websocketclientwrapper.cpp
@@ -55,6 +55,12 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    Construct the client wrapper with the given parent.
+
+    All clients connecting to the QWebSocketServer will be automatically wrapped
+    in WebSocketTransport objects.
+*/
 WebSocketClientWrapper::WebSocketClientWrapper(QWebSocketServer *server, QObject *parent)
     : QObject(parent)
     , m_server(server)
@@ -63,6 +69,9 @@ WebSocketClientWrapper::WebSocketClientWrapper(QWebSocketServer *server, QObject
             this, &WebSocketClientWrapper::handleNewConnection);
 }
 
+/*!
+    Wrap an incoming WebSocket connection in a WebSocketTransport object.
+*/
 void WebSocketClientWrapper::handleNewConnection()
 {
     emit clientConnected(new WebSocketTransport(m_server->nextPendingConnection()));
diff --git a/examples/standalone/websocketclientwrapper.h b/examples/qwebchannel/standalone/websocketclientwrapper.h
index 1f742f7..1f742f7 100644
--- a/examples/standalone/websocketclientwrapper.h
+++ b/examples/qwebchannel/standalone/websocketclientwrapper.h
diff --git a/examples/standalone/websockettransport.cpp b/examples/qwebchannel/standalone/websockettransport.cpp
index f1ecee2..5714463 100644
--- a/examples/standalone/websockettransport.cpp
+++ b/examples/qwebchannel/standalone/websockettransport.cpp
@@ -57,6 +57,11 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    Construct the transport object and wrap the given socket.
+
+    The socket is also set as the parent of the transport object.
+*/
 WebSocketTransport::WebSocketTransport(QWebSocket *socket)
 : QWebChannelAbstractTransport(socket)
 , m_socket(socket)
@@ -65,17 +70,26 @@ WebSocketTransport::WebSocketTransport(QWebSocket *socket)
             this, &WebSocketTransport::textMessageReceived);
 }
 
+/*!
+    Destroys the WebSocketTransport.
+*/
 WebSocketTransport::~WebSocketTransport()
 {
 
 }
 
+/*!
+    Serialize the JSON message and send it as a text message via the WebSocket to the client.
+*/
 void WebSocketTransport::sendMessage(const QJsonObject &message)
 {
     QJsonDocument doc(message);
     m_socket->sendTextMessage(QString::fromUtf8(doc.toJson(QJsonDocument::Compact)));
 }
 
+/*!
+    Deserialize the stringified JSON messageData and emit messageReceived.
+*/
 void WebSocketTransport::textMessageReceived(const QString &messageData)
 {
     QJsonParseError error;
diff --git a/examples/standalone/websockettransport.h b/examples/qwebchannel/standalone/websockettransport.h
index 828ac00..828ac00 100644
--- a/examples/standalone/websockettransport.h
+++ b/examples/qwebchannel/standalone/websockettransport.h