Provide example documentation for new chat example.

Change-Id: I073b0b4432d7e51516584aa1d23c681bb8544392
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

3 files changed, 102 insertions, 3 deletions

diff --git a/examples/bluetooth/chat/chat.qml b/examples/bluetooth/chat/chat.qml
index e89c6b11..ce4c6d3c 100644
--- a/examples/bluetooth/chat/chat.qml
+++ b/examples/bluetooth/chat/chat.qml
@@ -48,16 +48,19 @@ Item {
     property string remoteDeviceName: ""
     property bool serviceFound: false
 
+    //! [BtDiscoveryModel-1]
     BluetoothDiscoveryModel {
         id: btModel
         running: true
         discoveryMode: BluetoothDiscoveryModel.MinimalServiceDiscovery
+    //! [BtDiscoveryModel-1]
         onRunningChanged : {
             if (!btModel.running && top.state == "begin" && !serviceFound) {
                 searchBox.appendText("\nNo service found. \n\nPlease start server\nand restart app.")
             }
         }
 
+    //! [BtDiscoveryModel-2]
         onServiceDiscovered: {
             if (serviceFound)
                 return
@@ -67,26 +70,36 @@ Item {
             remoteDeviceName = service.deviceName
             socket.setService(service)
         }
+    //! [BtDiscoveryModel-2]
+    //! [BtDiscoveryModel-3]
         uuidFilter: "e8e10f95-1a70-4b27-9ccf-02010264e9c8"
     }
+    //! [BtDiscoveryModel-3]
 
+    //! [BluetoothSocket-1]
     BluetoothSocket {
         id: socket
         connected: true
 
-        onSocketStateChanged : {
+        onSocketStateChanged: {
             console.log("Connected to server")
             top.state = "chatActive"
         }
-
-        onStringDataChanged : {
+    //! [BluetoothSocket-1]
+    //! [BluetoothSocket-3]
+        onStringDataChanged: {
             console.log("Received data: " )
             var data = remoteDeviceName + ": " + socket.stringData;
             data = data.substring(0, data.indexOf('\n'))
             chatContent.append({content: data})
+    //! [BluetoothSocket-3]
             console.log(data);
+    //! [BluetoothSocket-4]
         }
+    //! [BluetoothSocket-4]
+    //! [BluetoothSocket-2]
     }
+    //! [BluetoothSocket-2]
 
     ListModel {
         id: chatContent
@@ -128,7 +141,9 @@ Item {
             var data = input.text
             input.clear()
             chatContent.append({content: "Me: " + data})
+            //! [BluetoothSocket-5]
             socket.stringData = data
+            //! [BluetoothSocket-5]
             chatView.positionViewAtEnd()
         }
 
diff --git a/examples/bluetooth/chat/doc/images/chat-view.png b/examples/bluetooth/chat/doc/images/chat-view.png
new file mode 100644
index 00000000..13eeede7
--- /dev/null
+++ b/examples/bluetooth/chat/doc/images/chat-view.png
diff --git a/examples/bluetooth/chat/doc/src/chat.qdoc b/examples/bluetooth/chat/doc/src/chat.qdoc
new file mode 100644
index 00000000..5f61fd74
--- /dev/null
+++ b/examples/bluetooth/chat/doc/src/chat.qdoc
@@ -0,0 +1,84 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt local connectivty modules.
+**
+** $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$
+**
+****************************************************************************/
+
+/*!
+    \example chat
+    \title Bluetooth QML Chat Example
+    \brief An example demonstrating communication through Bluetooth QML API.
+
+    \e {Bluetooth QML Chat} example shows how to use the \l{Qt Bluetooth} QML API to communicate
+    with another application on a remote device using Bluetooth.
+
+    \image chat-view.png
+
+    The Bluetooth QML Chat example implements a simple chat program between two parties. The
+    application acts as client and attempts to connect to a Bluetooth socket server. It uses
+    the \l BluetoothDiscoveryModel type to find the server and \l BluetoothSocket type to
+    facilitate the data exchange.
+
+    \include examples-run.qdocinc
+
+    The example only works in connection with the \l {btchat}{Bluetooth Chat Example}.
+    The Bluetooth Chat example launches the chat service and advertises it via the
+    Bluetooth SDP protocol. It is important that the device running the Bluetooth Chat
+    example actively advertises its SDP services.
+    This can be checked using the \l QBluetoothLocalDevice::hostMode property.
+
+    \section1 Interacting with the Server
+
+    The example application immediately starts the service discovery using the
+    \l BluetoothDiscoveryModel type:
+
+    \snippet chat/chat.qml BtDiscoveryModel-1
+    \snippet chat/chat.qml BtDiscoveryModel-3
+
+    The \l {BluetoothDiscoveryModel::uuidFilter}{uuidFilter} property is used to only search for
+    the chat server UUID and the \l {BluetoothDiscoveryModel::running}{running}
+    property activates the search. Once a service with a matching UUID is found the model emits the
+    \l {BluetoothDiscoveryModel::serviceDiscovered}{serviceDiscovered(BluetoothService)} signal.
+
+    \snippet chat/chat.qml BtDiscoveryModel-2
+
+    The \l BluetoothService type encapsulates the details of the found chat server, such as the
+    \l {BluetoothService::serviceName}{name} and \l {BluetoothService::serviceDescription}{description} of the
+    service, as well as the \l{BluetoothService::deviceName}{name} and \l {BluetoothService::deviceAddress}{address}
+    of the Bluetooth device offering the chat server. It is passed to the \l BluetoothSocket
+    to establish the connection.
+
+    Once the connection is established the chat information is:
+    \snippet chat/chat.qml BluetoothSocket-1
+    \snippet chat/chat.qml BluetoothSocket-2
+
+    The payload is received via the \l {BluetoothSocket::stringData}{stringData} property:
+
+    \snippet chat/chat.qml BluetoothSocket-3
+    \snippet chat/chat.qml BluetoothSocket-4
+
+    And sent by setting the same property:
+
+    \snippet chat/chat.qml BluetoothSocket-5
+*/