Added overview documentation for the radio

Change-Id: I71b072512db51f23b0aed82545b504f9efc824d0
Reviewed-by: Dmytro Poplavskiy <dmytro.poplavskiy@nokia.com>

7 files changed, 102 insertions, 0 deletions

diff --git a/doc/src/images/declarative-radio-example.png b/doc/src/images/declarative-radio-example.png
new file mode 100644
index 000000000..6c0393499
--- /dev/null
+++ b/doc/src/images/declarative-radio-example.png
diff --git a/doc/src/images/radio-example.png b/doc/src/images/radio-example.png
new file mode 100644
index 000000000..2fdb1b258
--- /dev/null
+++ b/doc/src/images/radio-example.png
diff --git a/doc/src/radiooverview.qdoc b/doc/src/radiooverview.qdoc
new file mode 100644
index 000000000..b49281b7b
--- /dev/null
+++ b/doc/src/radiooverview.qdoc
@@ -0,0 +1,95 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+
+\page radiooverview.html
+\title Radio Overview
+\brief An API to control system radio tuner
+
+The Radio API provides control over the radio tuner of the system, and
+gives access to Radio Data System (RDS) information for radio stations that
+broadcasts it.
+
+\section1 Radio Features
+
+The Radio API consists of two separate components. The radio tuner,
+\l QRadioTuner or the \l Radio QML element, which handles control of
+the radio hardware as well as tuning. The other is the radio data
+component, either \l QRadioData or the \l RadioData QML element, which
+gives access to RDS information.
+
+\section1 Radio Implementation Details
+
+The actual level of support depends on the underlying system support. It should
+be noted that only analog radio is supported, and the properties of the radio
+data component will only be populated if the system radio tuner supports RDS.
+
+\section1 Examples
+
+There are two examples showing the usage of the Radio API. One shows how to use
+the QRadioTuner class from C++. The other shows how to implement a similar
+application using QML and the Radio element.
+
+\section2 Radio Example
+
+This image shows the example using the QRadioTuner API.
+
+\image radio-example.png
+
+The example reads the frequency from the radio tuner, and sets the "Got Signal"
+text based on the signal strength. The buttons allow the user to tune and scan
+up and down the frequency band, while the slider to the side allows volume
+adjustments.
+
+Only the FM frequency band is used in this example.
+
+\section2 Declarative Radio Example
+
+\image declarative-radio-example.png
+
+This example has the same functionality of the regular radio example mentioned
+above, but it includes a nice horizontal dial showing the position of the
+current frequency inside the band.
+
+\section1 Reference documentation
+
+\section2 Radio Classes
+
+\list
+    \o \l QRadioTuner
+    \o \l QRadioData
+\endlist
+
+\section2 QML Elements
+
+\list
+    \o \l Radio
+    \o \l RadioData
+\endlist
+
+*/
diff --git a/src/imports/multimedia/qdeclarativeradio.cpp b/src/imports/multimedia/qdeclarativeradio.cpp
index e6dedbbcf..2732d3d4a 100644
--- a/src/imports/multimedia/qdeclarativeradio.cpp
+++ b/src/imports/multimedia/qdeclarativeradio.cpp
@@ -89,6 +89,8 @@ QT_BEGIN_NAMESPACE
 
     The corresponding \l RadioData element gives RDS information about the current radio station.
 
+    \sa {Radio Overview}
+
 */
 
 
diff --git a/src/imports/multimedia/qdeclarativeradiodata.cpp b/src/imports/multimedia/qdeclarativeradiodata.cpp
index 69fad7106..860a454aa 100644
--- a/src/imports/multimedia/qdeclarativeradiodata.cpp
+++ b/src/imports/multimedia/qdeclarativeradiodata.cpp
@@ -93,6 +93,8 @@ QT_BEGIN_NAMESPACE
 
     You use \c RadioData together with the \l Radio element. The properties of the RadioData element will reflect the
     information broadcast by the radio station the Radio element is currently tuned to.
+
+    \sa {Radio Overview}
 */
 QDeclarativeRadioData::QDeclarativeRadioData(QObject *parent) :
     QObject(parent),
diff --git a/src/multimedia/radio/qradiodata.cpp b/src/multimedia/radio/qradiodata.cpp
index b750b1ad9..4a15607a3 100644
--- a/src/multimedia/radio/qradiodata.cpp
+++ b/src/multimedia/radio/qradiodata.cpp
@@ -74,6 +74,8 @@ namespace
     The radio data object will emit signals for any changes in radio data. You can enable or disable
     alternative frequency with setAlternativeFrequenciesEnabled().
 
+    \sa {Radio Overview}
+
 */
 
 
diff --git a/src/multimedia/radio/qradiotuner.cpp b/src/multimedia/radio/qradiotuner.cpp
index be875a78b..3d5323b2a 100644
--- a/src/multimedia/radio/qradiotuner.cpp
+++ b/src/multimedia/radio/qradiotuner.cpp
@@ -86,6 +86,7 @@ namespace
     You can change between the frequency bands using setBand() however it is recommended
     that you check to make sure the band is available first using isBandSupported().
 
+    \sa {Radio Overview}
 */