Qt Bluetooth: Modularized documentation

-moved documentation to src/bluetooth/doc
-added a qdocconf file for Qt Bluetooth
-fixed relative paths for snippets
-moved examples to examples/bluetooth

Change-Id: Id41bac50dca628400568d191f1c3ccfbaac790a1
Reviewed-by: Alex <ablasche@gmail.com>

5 files changed, 375 insertions, 0 deletions

diff --git a/src/bluetooth/doc/src/bluetooth-cpp.qdoc b/src/bluetooth/doc/src/bluetooth-cpp.qdoc
new file mode 100644
index 00000000..4dcb6021
--- /dev/null
+++ b/src/bluetooth/doc/src/bluetooth-cpp.qdoc
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+
+
+/*!
+
+\page bluetooth-cpp.html
+
+\title Qt Bluetooth C++ API
+\brief An API enabling basic Bluetooth operations like scanning for devices
+and connecting them.
+
+\ingroup qtconnectivity
+\ingroup qtconnectivity-c++
+
+The Qt Bluetooth C++ API enables an application to scan for devices and connect and
+interact with them in a more flexible way than the \l{Qt Bluetooth QML API}.
+
+\section1 Classes
+
+\list
+\annotatedlist connectivity-bluetooth
+\endlist
+
+*/
+
diff --git a/src/bluetooth/doc/src/bluetooth-index.qdoc b/src/bluetooth/doc/src/bluetooth-index.qdoc
new file mode 100644
index 00000000..371de05c
--- /dev/null
+++ b/src/bluetooth/doc/src/bluetooth-index.qdoc
@@ -0,0 +1,95 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** 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 qtbluetooth-index.html
+    \title Qt Bluetooth
+    \brief Qt Bluetooth enables connectivity between Bluetooth enabled devices.
+
+    Bluetooth is a short-range (less than 100 meters) wireless technology. It
+    has a reasonably high data transfer rate of 2.1 Mbit/s, which makes it ideal
+    for transfering data between devices.
+
+    Bluetooth connectivity is based on basic device management, such as scanning
+    for devices, gathering information about them, and exchaning data between
+    them.
+
+    \section1 Getting Started
+
+    To use the C++ library in your application, add the following configuration
+    option to your \c .pro file:
+
+    \snippet doc_src_qtbluetooth.pro contacts project modification
+
+    To use the classes of the module in your application you need the following
+    import statement in your \c .qml file:
+
+    \snippet doc_src_qtbluetooth.qml import
+
+    \section1 References
+
+    \table
+    \header
+        \li {1,4} Reference
+        \li {1,4} Guides
+        \li {4,1} Examples
+    \header
+      \li QML API examples
+      \li C++ API examples
+    \row
+        \li \l{Qt Bluetooth QML API}
+        \li \l{Qt Bluetooth Overview}
+        \li \l{btscanner}{QML Bluetooth Scanner}
+
+            A QML implementation of the Bluetooth device scanner.
+        \li \l{btscanner}{Bluetooth Scanner}
+
+            Scan for Bluetooth devices.
+    \row
+        \li \l{Qt Bluetooth C++ API}
+        \li \l{btchat}{Qt Bluetooth Tutorial}
+
+            A chat server and client using bluetooth.
+        \li \l{bttennis}{QML Bluetooth Tennis}
+
+            The tennis game using a QML interface to the Qt Bluetooth QML API.
+            It must connect to an instance of the C++ tennis game to play.
+        \li \l{bttennis}{Bluetooth Tennis}
+
+            The classic game of \l{http://en.wikipedia.org/wiki/Pong}{Pong}.
+            Supports multiplayer over Bluetooth and touch-to-play
+            functionality on devices that support NFC.
+    \row
+        \li
+        \li
+        \li
+        \li \l{btfiletransfer}{Bluetooth File Transfer}
+
+            Transfer files between Bluetooth devices.
+    \endtable
+
+*/
diff --git a/src/bluetooth/doc/src/bluetooth-overview.qdoc b/src/bluetooth/doc/src/bluetooth-overview.qdoc
new file mode 100644
index 00000000..d62321f7
--- /dev/null
+++ b/src/bluetooth/doc/src/bluetooth-overview.qdoc
@@ -0,0 +1,104 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+/*!
+\ingroup technology-apis
+\title Qt Bluetooth Overview
+\page qtbluetooth-overview.html
+\brief The Qt Bluetooth API enables connectivity with other Bluetooth enabled devices.
+
+\tableofcontents
+
+    With the Qt Bluetooth API typical use cases are:
+
+        \list
+        \li Retrieve information about the local Bluetooth device.
+        \li Scan for other Bluetooth devices in range and retrieve information about them.
+        \li Push files to remote devices using the OBEX Object Push Profile (OPP).
+        \li Connect to remote devices through a RFCOMM channel using the Serial Port Profile (SPP).
+        \li Create a RFCOMM server that allows incoming connections using SPP.
+        \endlist
+
+    The following sections describe how to use the Qt Bluetooth C++ API classes
+    for the above use cases.
+
+    \section1 Retrieving Local Device Information
+
+    The Qt Bluetooth API has three main purposes. The first one is to
+    obtain local and remote device information. The first steps in retrieving device information is
+    to check if Bluetooth is available on the device and read the local device address and name. The
+    QBluetoothLocalDevice is the one to provide all of this information. Additionally you can use it
+    to turn Bluetooth on and off and set the visibility on the device.
+
+    \snippet doc_src_qtbluetooth.cpp turningon
+
+    \section1 Scanning for Bluetooth Devices
+
+    Similar to the QBluetoothLocalDevice, the API offers QBluetoothDeviceInfo which provides
+    that information for remote devices. While you can just create QBluetoothDeviceInfo objects on
+    your own and fill them with data, the easier way is to use the QBluetoothDeviceDiscoveryAgent to
+    start an automated search for visible Bluetooth devices within the connectable range.
+
+    \snippet doc_src_qtbluetooth.cpp discovery
+
+    \section1 Pushing Files to Remote Devices
+
+    Once the desired device is found, there are two main use cases provided by Qt Bluetooth. The
+    simpler is to send files via the Obex Object Push Profile (OPP). As the name describes, this
+    profile can only push files from one device to another but not pull files or browse the remote
+    file system. Because of this limitation, this profile does not require the two devices to be
+    paired before exchanging data. To push files to remote devices, create a
+    QBluetoothTransferRequest and ask the QBluetoothTransferManager to push the file contained in
+    the request by calling the put() function.
+
+    \snippet doc_src_qtbluetooth.cpp sendfile
+
+    \section1 Exchanging Data Between Devices
+
+    The more flexible approach to do communication between two Bluetooth enabled devices, is to
+    create a virtual serial port connection and freely exchange data over that connection. This can
+    be done by the Serial Port Profile (SPP). The Serial Port Profile emulates a serial connection
+    over the Bluetooth transport protocol RFCOMM.
+
+    To be able to create SPP connections, you need to register a Server one one device by using
+    QRfcommServer.
+
+    \snippet chatserver.cpp Create the server
+
+    Connect to this server from another device playing the client role by using a
+    QBluetoothSocket.
+
+    \snippet chatclient.cpp startClient
+
+    Using such a connection allows to exchange any form of data in both directions.
+    It is perfectly suited for use cases like gaming or syncing the state between two instances of
+    an application on two devices. For more detailed descriptions on how to configure the server
+    and client, please refer to the detailed description sections in the QRfcommServer and
+    QBluetoothSocket classes. A good example to start with SPP is the \l{btchat}{Bluetooth Chat}
+    example.
+
+*/
diff --git a/src/bluetooth/doc/src/bluetooth-qml.qdoc b/src/bluetooth/doc/src/bluetooth-qml.qdoc
new file mode 100644
index 00000000..36c4d4fd
--- /dev/null
+++ b/src/bluetooth/doc/src/bluetooth-qml.qdoc
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+
+/*!
+
+\page bluetooth-qml.html
+
+\title Qt Bluetooth QML API
+\brief A QML API enabling basic Bluetooth operations like scanning for devices
+and connecting them.
+
+\ingroup qtconnectivity
+\ingroup qtconnectivity-qml
+
+The Qt Bluetooth QML API enables an application to scan for devices and connect and
+interact with them in an easier way than the C++ Classes. However, it is a bit
+more limited than the C++ API. You can always use the C++ API to create QML
+plugins with the flexibility you need.
+
+\tableofcontents
+
+\section1 QML Types
+
+\list
+\annotatedlist bluetooth-qml
+\endlist
+
+*/
+
diff --git a/src/bluetooth/doc/src/examples.qdoc b/src/bluetooth/doc/src/examples.qdoc
new file mode 100644
index 00000000..da6503c9
--- /dev/null
+++ b/src/bluetooth/doc/src/examples.qdoc
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+/*!
+    \ingroup all-examples
+    \page bluetooth-examples.html
+    \title Qt Bluetooth Examples
+    \brief Examples for the QtBluetooth module
+
+    This is a variety of examples that cover the entire range of the the Qt Bluetooth API. You will find them in their own documentation but are also accessible from here.
+
+    \section2 C++ Tutorial
+    The \l{btchat}{Bluetooth Chat} example contains a tutorial on how to use the C++ API to create a RFCOMM server and client and exchange data between them.
+
+    \section2 C++ Examples
+    \table 80%
+        \header
+            \li Example
+            \li Description
+        \row
+            \li \l{bttennis}{Bluetooth Tennis}
+            \li The classic game of \l {http://en.wikipedia.org/wiki/Pong}{Pong}. Supports multiplayer
+            over Bluetooth and touch-to-play functionality on devices that support NFC.
+        \row
+            \li \l{btfiletransfer}{Bluetooth File Transfer}
+            \li Transfer files between Bluetooth devices.
+        \row
+            \li \l{btscanner}{Bluetooth Scanner}
+            \li Scan for Bluetooth devices.
+    \endtable
+
+    \section2 QML Examples
+    \table 80%
+        \header
+            \li Example
+            \li Description
+        \row
+            \li \l{bttennis}{QML Bluetooth Tennis}
+            \li The tennis game using a QML interface to the Bluetooth API. It must connect to an
+            instance of the C++ \l{bttennis}{Bluetooth Tennis} game to play.
+        \row
+            \li \l{btscanner}{QML Bluetooth Scanner}
+            \li A QML implementation of the Bluetooth device scanner.
+    \endtable
+
+*/
+