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>

1 files changed, 22 insertions, 54 deletions

diff --git a/README.md b/README.md
index 185c4fd..111c76f 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,22 @@
 ### Introduction
 
-The `QtWebChannel` module offers Qt applications a seamless way to publish `QObjects` for interaction
-from HTML/JavaScript clients. These clients can either be inside local Qt `WebView`s or any other,
-potentially remote, client which supports JavaScript and WebSockets.
+The Qt WebChannel module offers Qt applications a seamless way to publish `QObjects` for interaction
+with HTML/JavaScript clients. These clients can either be inside local Qt `WebView`s or any other,
+potentially remote, client which supports JavaScript, as long as a communication channel such
+as WebSockets is available.
 
-It uses introspection on the `QObject`s and sends this serialized data to the clients. There, with
-the help of a small JavaScript library, an object is created which simulates the API of the `QObject`.
-Any invokable methods, including slots, can be called as well as properties read and written.
-Additionally you can connect to signals and register JavaScript callbacks as handlers.
+Qt WebChannel uses introspection on the `QObject`s and sends this serialized data to the clients.
+There, with the help of a small JavaScript library, an object is created which simulates the API of
+the `QObject`. Any invokable methods, including slots, can be called as well as properties read and
+written. Additionally you can connect to signals and register JavaScript callbacks as handlers.
 
 ### Dependencies
 
-This module depends on `QtBase` and `QtWebSockets`. Optionally, an additional module for QtQuick is
-build which makes it easy to use the `QWebChannel` from QML. Furthermore, you can decide to use the
-native IPC mechanism of `QtWebKit` for efficient message passing to QtQuick `WebView`'s.
+This module depends on Qt Core only. Optionally, an additional plugin for Qt Quick is build, which
+makes it easy to use a `QWebChannel` from QML. Note that this module alone is not functional. It
+is being used in e.g. Qt WebKit to provide a seamless integration of QML/C++ QObjects into JavaScript
+clients. You can integrate it in your projects as well, by providing an implementation of the
+`QWebChannelAbstractTransport` class, see the `standalone` example for how to do this.
 
 ### Building
 
@@ -27,64 +30,29 @@ To use the Qt/C++ library, add the following to your `QMake` project:
 
     QT += webchannel
 
-Then, in your C++ code, construct a websocket transport and webchannel, then publish your `QObject`s:
+Then, in your C++ code, construct a a webchannel, then publish your `QObject`s:
 
-    QWebSocketTransport transport;
     QWebChannel channel;
-    channel.connectTo(&transport);
-
     channel.registerObject(QStringLiteral("foo"), myFooObj);
     ....
 
-On the HTML/JavaScript client side, you need to embed `src/webchannel/qwebchannel.js` and setup
-the connection to the WebSocket transport. The base URL for that can be found from C++ via
-`transport.baseUrl()` after the transport was initialized, and must be passed to HTML clients:
-
-    <script type="text/javascript" src="path/to/qwebchannel.js"></script>
-    <script type="text/javascript">
-    // note: baseUrl must be known
-    new QWebChannel(baseUrl, function(channel) {
-        foo.doStuff(); // calls doStuff slot or invokable method on myFooObj on the C++ side
-    });
-    </script>
+Additionally, you need to provide a communication channel to the HTML client. One way is to
+use the Qt WebSockets module. On the HTML/JavaScript client side, you need to embed
+`src/webchannel/qwebchannel.js` and setup the connection to a client-side transport. An example
+which shows all this in action can be found in `examples/standalone`.
 
-An example which shows all this can be found in `examples/standalone`.
-
-### Usage from QtQuick
+### Usage from Qt Quick
 
 For QML applications, use the following import:
 
     import QtWebChannel 1.0
 
-Then setup the WebChannel and register objects to it:
+Then setup the WebChannel, register objects to it and connect to transport objects:
 
     WebChannel {
         registeredObjects: [foo, bar, ...]
 
-        connections: WebViewTransport {
-            webViewExperimental: yourWebView.experimental
-            onMessageReceived: {
-                textEdit.text += "Received message: " + message + "\n";
-            }
-        }
-    }
-
-The above uses a `WebViewTransport` for efficient message passing between the server QML application
-and HTML clients in a `WebView`, which must be setup as follows:
-
-    WebView {
-        id: yourWebView
-        experimental.preferences.navigatorQtObjectEnabled: true
+        transports: [yourTransport]
     }
 
-The HTML client finally uses a similar setup as above, but can make use of the embedded resource
-for `qwebchannel.js` and the `navigator.qt` object:
-
-    <script type="text/javascript" src="qrc:///qwebchannel/qwebchannel.js"></script>
-    <script type="text/javascript">
-    new QWebChannel(navigator.qt, function(channel) {
-        // do stuff with published objects
-    });
-    </script>
-
-To see this in action, take a look at `examples/qml` and run the `example.qml` in `qmlscene`.
+To see this in action, take a look at the test code in `tests/auto/qml`.