Added documentation for the Radio and RadioData QML elements.

Change-Id: I60c98b23138664543a1738ae93043432f66c8ab8
Reviewed-by: Michael Goddard <michael.goddard@nokia.com>

2 files changed, 422 insertions, 0 deletions

diff --git a/src/imports/multimedia/qdeclarativeradio.cpp b/src/imports/multimedia/qdeclarativeradio.cpp
index 9eeb3ac3b..e6dedbbcf 100644
--- a/src/imports/multimedia/qdeclarativeradio.cpp
+++ b/src/imports/multimedia/qdeclarativeradio.cpp
@@ -43,6 +43,55 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass Radio QDeclarativeRadio
+    \since 5.0.0
+    \brief The Radio element allows you to access radio functionality from a QML application.
+    \ingroup qml-multimedia
+    \inherits Item
+
+    This element is part of the \bold{QtMultimedia 5.0} module.
+
+    \qml
+    import QtQuick 2.0
+    import QtMultimedia 5.0
+
+    Rectangle {
+        width: 320
+        height: 480
+
+        Radio {
+            id: radio
+            band: Radio.FM
+        }
+
+        MouseArea {
+            x: 0; y: 0
+            height: parent.height
+            width: parent.width / 2
+
+            onClicked: radio.scanDown()
+        }
+
+        MouseArea {
+            x: parent.width / 2; y: 0
+            height: parent.height
+            width: parent.width / 2
+
+            onClicked: radio.scanUp()
+        }
+    }
+    \endqml
+
+    You can use the \c Radio element to tune the radio and get information about the signal.
+    You can also use the Radio element to get information about tuning, for instance the
+    frequency steps supported for tuning.
+
+    The corresponding \l RadioData element gives RDS information about the current radio station.
+
+*/
+
+
 QDeclarativeRadio::QDeclarativeRadio(QObject *parent) :
     QObject(parent),
     m_radioTuner(0)
@@ -67,66 +116,187 @@ QDeclarativeRadio::~QDeclarativeRadio()
 {
 }
 
+/*!
+    \qmlproperty enumeration Radio::state
+
+    This property holds the current state of the Radio element.
+
+    \table
+    \header \o Value \o Description
+    \row \o ActiveState
+        \o The radio is started and active
+
+    \row \o StoppedState
+        \o The radio is stopped
+
+    \endtable
+
+    \sa start, stop
+*/
 QDeclarativeRadio::State QDeclarativeRadio::state() const
 {
     return static_cast<QDeclarativeRadio::State>(m_radioTuner->state());
 }
 
+/*!
+    \qmlproperty enumeration Radio::band
+
+    This property holds the frequency band used for the radio, which can be specified as
+    any one of the values in the table below.
+
+    \table
+    \header \o Value \o Description
+    \row \o AM
+        \o 520 to 1610 kHz, 9 or 10kHz channel spacing, extended 1610 to 1710 kHz
+
+    \row \o FM
+        \o 87.5 to 108.0 MHz, except Japan 76-90 MHz
+
+    \row \o SW
+        \o 1.711 to 30.0 MHz, divided into 15 bands. 5kHz channel spacing
+
+    \row \o LW
+        \o 148.5 to 283.5 kHz, 9kHz channel spacing (Europe, Africa, Asia)
+
+    \row \o FM2
+        \o range not defined, used when area supports more than one FM range
+
+    \endtable
+*/
 QDeclarativeRadio::Band QDeclarativeRadio::band() const
 {
     return static_cast<QDeclarativeRadio::Band>(m_radioTuner->band());
 }
 
+/*!
+    \qmlproperty int Radio::frequency
+
+    Sets the frequency in Hertz that the radio is tuned to. The frequency must be within the frequency
+    range for the current band, otherwise it will be changed to be within the frequency range.
+
+    \sa maximumFrequency, minimumFrequency
+*/
 int QDeclarativeRadio::frequency() const
 {
     return m_radioTuner->frequency();
 }
 
+/*!
+    \qmlproperty enumeration Radio::stereoMode
+
+    This property holds the stereo mode of the radio, which can be set to any one of the
+    values in the table below.
+
+    \table
+    \header \o Value \o Description
+    \row \o Auto
+        \o Uses stereo mode matching the station
+
+    \row \o ForceStereo
+        \o Forces the radio to play the station in stereo, converting the sound signal if necessary
+
+    \row \o ForceMono
+        \o Forces the radio to play the station in mono, converting the sound signal if necessary
+
+    \endtable
+*/
 QDeclarativeRadio::StereoMode QDeclarativeRadio::stereoMode() const
 {
     return static_cast<QDeclarativeRadio::StereoMode>(m_radioTuner->stereoMode());
 }
 
+/*!
+    \qmlproperty int Radio::volume
+
+    Set this property to control the volume of the radio. The valid range of the volume is from 0 to 100.
+*/
 int QDeclarativeRadio::volume() const
 {
     return m_radioTuner->volume();
 }
 
+/*!
+    \qmlproperty bool Radio::muted
+
+    This property reflects whether the radio is muted or not.
+*/
 bool QDeclarativeRadio::muted() const
 {
     return m_radioTuner->isMuted();
 }
 
+/*!
+    \qmlproperty bool Radio::stereo
+
+    This property holds whether the radio is receiving a stereo signal or not. If \l stereoMode is
+    set to ForceMono the value will always be false. Likewise, it will always be true if stereoMode
+    is set to ForceStereo.
+
+    \sa stereoMode
+*/
 bool QDeclarativeRadio::stereo() const
 {
     return m_radioTuner->isStereo();
 }
 
+/*!
+    \qmlproperty int Radio::signalStrength
+
+    The strength of the current radio signal as a percentage where 0% equals no signal, and 100% is a
+    very good signal.
+*/
 int QDeclarativeRadio::signalStrength() const
 {
     return m_radioTuner->signalStrength();
 }
 
+/*!
+    \qmlproperty bool Radio::searching
+
+    This property is true if the radio is currently searching for radio stations, for instance using the \l scanUp,
+    \l scanDown, and \l searchAllStations methods. Once the search completes, or if it is cancelled using
+    \l cancelScan, this property will be false.
+*/
 bool QDeclarativeRadio::searching() const
 {
     return m_radioTuner->isSearching();
 }
 
+/*!
+    \qmlproperty int Radio::frequencyStep
+
+    The number of Hertz for each step when tuning the radio manually. The value is for the current \l band.
+ */
 int QDeclarativeRadio::frequencyStep() const
 {
     return m_radioTuner->frequencyStep(m_radioTuner->band());
 }
 
+/*!
+    \qmlproperty int Radio::minimumFrequency
+
+    The minimum frequency for the current \l band.
+ */
 int QDeclarativeRadio::minimumFrequency() const
 {
     return m_radioTuner->frequencyRange(m_radioTuner->band()).first;
 }
 
+/*!
+    \qmlproperty int Radio::maximumFrequency
+
+    The maximum frequency for the current \l band.
+ */
 int QDeclarativeRadio::maximumFrequency() const
 {
     return m_radioTuner->frequencyRange(m_radioTuner->band()).second;
 }
 
+/*!
+    \qmlmethod bool Radio::isAvailable()
+
+    Returns whether the radio is ready to use.
+ */
 bool QDeclarativeRadio::isAvailable() const
 {
     return m_radioTuner->isAvailable();
@@ -157,26 +327,103 @@ void QDeclarativeRadio::setMuted(bool muted)
     m_radioTuner->setMuted(muted);
 }
 
+/*!
+    \qmlmethod Radio::cancelScan()
+
+    Cancel the current scan. Will also cancel a search started with \l searchAllStations.
+ */
 void QDeclarativeRadio::cancelScan()
 {
     m_radioTuner->cancelSearch();
 }
 
+/*!
+    \qmlmethod Radio::scanDown()
+
+    Searches backward in the frequency range for the current band.
+ */
 void QDeclarativeRadio::scanDown()
 {
     m_radioTuner->searchBackward();
 }
 
+/*!
+    \qmlmethod Radio::scanUp()
+
+    Searches forward in the frequency range for the current band.
+ */
 void QDeclarativeRadio::scanUp()
 {
     m_radioTuner->searchForward();
 }
 
+/*!
+    \qmlmethod Radio::searchAllStations(enumeration searchMode)
+
+    Start searching the complete frequency range for the current band, and save all the
+    radio stations found. The search mode can be either of the values described in the
+    table below.
+
+    \table
+    \header \o Value \o Description
+    \row \o SearchFast
+        \o Stores each radio station for later retrival and tuning
+
+    \row \o SearchGetStationId
+        \o Does the same as SearchFast, but also emits the station Id with the \l stationFound signal.
+
+    \endtable
+
+    The snippet below uses \c searchAllStations with \c SearchGetStationId to receive all the radio
+    stations in the current band, and store them in a ListView. The station Id is shown to the user
+    and if the user presses a station, the radio is tuned to this station.
+
+    \qml
+    Radio {
+        id: radio
+        onStationFound: radioStations.append({"frequency": frequency, "stationId": stationId})
+    }
+
+    ListModel {
+        id: radioStations
+    }
+
+    ListView {
+        model: radioStations
+        delegate: Rectangle {
+                MouseArea {
+                    anchors.fill: parent
+                    onClicked: radio.frequency = frequency
+                }
+
+                Text {
+                    anchors.fill: parent
+                    text: stationId
+                }
+            }
+    }
+
+    Rectangle {
+        MouseArea {
+            anchors.fill: parent
+            onClicked: radio.searchAllStations(Radio.SearchGetStationId)
+        }
+    }
+    \endqml
+ */
 void QDeclarativeRadio::searchAllStations(QDeclarativeRadio::SearchMode searchMode)
 {
     m_radioTuner->searchAllStations(static_cast<QRadioTuner::SearchMode>(searchMode));
 }
 
+/*!
+    \qmlmethod Radio::tuneDown()
+
+    Decrements the frequency by the frequency step for the current band. If the frequency is already set
+    to the minimum frequency, calling this function has no effect.
+
+    \sa band, frequencyStep, minimumFrequency
+ */
 void QDeclarativeRadio::tuneDown()
 {
     int f = frequency();
@@ -184,6 +431,14 @@ void QDeclarativeRadio::tuneDown()
     setFrequency(f);
 }
 
+/*!
+    \qmlmethod Radio::tuneUp()
+
+    Increments the frequency by the frequency step for the current band. If the frequency is already set
+    to the maximum frequency, calling this function has no effect.
+
+    \sa band, frequencyStep, maximumFrequency
+ */
 void QDeclarativeRadio::tuneUp()
 {
     int f = frequency();
@@ -191,11 +446,22 @@ void QDeclarativeRadio::tuneUp()
     setFrequency(f);
 }
 
+/*!
+    \qmlmethod Radio::start()
+
+    Starts the radio. If the radio is available, as determined by the \l isAvailable method,
+    this will result in the \l state becoming \c ActiveState.
+ */
 void QDeclarativeRadio::start()
 {
     m_radioTuner->start();
 }
 
+/*!
+    \qmlmethod Radio::stop()
+
+    Stops the radio. After calling this method the \l state will be \c StoppedState.
+ */
 void QDeclarativeRadio::stop()
 {
     m_radioTuner->stop();
@@ -217,4 +483,14 @@ void QDeclarativeRadio::_q_error(QRadioTuner::Error errorCode)
     emit errorChanged();
 }
 
+/*!
+    \qmlsignal Radio::stationFound(int frequency, string stationId)
+
+    This signal is emitted when a new radio station is found. This signal is only emitted
+    if \l searchAllStations is called with \c SearchGetStationId.
+
+    The \a frequency is returned in Hertz, and the \a stationId corresponds to the station Id
+    in the \l RadioData element for this radio station.
+  */
+
 QT_END_NAMESPACE
diff --git a/src/imports/multimedia/qdeclarativeradiodata.cpp b/src/imports/multimedia/qdeclarativeradiodata.cpp
index 1b6e9984f..69fad7106 100644
--- a/src/imports/multimedia/qdeclarativeradiodata.cpp
+++ b/src/imports/multimedia/qdeclarativeradiodata.cpp
@@ -43,6 +43,57 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass RadioData QDeclarativeRadioData
+    \since 5.0.0
+    \brief The RadioData element allows you to access RDS data from a QML application.
+    \ingroup qml-multimedia
+    \inherits Item
+
+    This element is part of the \bold{QtMultimedia 5.0} module.
+
+    The \c RadioData element is your gateway to all the data available through RDS. RDS is the Radio Data System
+    which allows radio stations to broadcast information like the \l stationId, \l programType, \l programTypeName,
+    \l stationName, and \l radioText. This information can be read from the \c RadioData element. It also allows
+    you to set whether the radio should tune to alternative frequencies if the current signal strength falls too much.
+
+    \qml
+    import QtQuick 2.0
+    import QtMultimedia 5.0
+
+    Rectangle {
+        width: 480
+        height: 320
+
+        Radio {
+            id: radio
+            band: Radio.FM
+        }
+
+        RadioData {
+            id: radioData
+        }
+
+        Column {
+            Text {
+                text: radioData.stationName
+            }
+
+            Text {
+                text: radioData.programTypeName
+            }
+
+            Text {
+                text: radioData.radioText
+            }
+        }
+    }
+
+    \endqml
+
+    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.
+*/
 QDeclarativeRadioData::QDeclarativeRadioData(QObject *parent) :
     QObject(parent),
     m_radioData(0)
@@ -66,36 +117,131 @@ QDeclarativeRadioData::~QDeclarativeRadioData()
 {
 }
 
+/*!
+    \qmlmethod bool RadioData::isAvailable()
+
+    Returns whether the radio data element is ready to use.
+  */
 bool QDeclarativeRadioData::isAvailable() const
 {
     return m_radioData->isAvailable();
 }
 
+/*!
+    \qmlproperty string RadioData::stationId
+
+    This property allows you to read the station Id of the currently tuned radio
+    station.
+  */
 QString QDeclarativeRadioData::stationId() const
 {
     return m_radioData->stationId();
 }
 
+/*!
+    \qmlproperty enumeration RadioData::programType
+
+    This property holds the type of the currently playing program as transmitted
+    by the radio station. The value can be any one of the values defined in the
+    table below.
+
+    \table
+    \header \o Value
+        \row \o Undefined
+        \row \o News
+        \row \o CurrentAffairs
+        \row \o Information
+        \row \o Sport
+        \row \o Education
+        \row \o Drama
+        \row \o Culture
+        \row \o Science
+        \row \o Varied
+        \row \o PopMusic
+        \row \o RockMusic
+        \row \o EasyListening
+        \row \o LightClassical
+        \row \o SeriousClassical
+        \row \o OtherMusic
+        \row \o Weather
+        \row \o Finance
+        \row \o ChildrensProgrammes
+        \row \o SocialAffairs
+        \row \o Religion
+        \row \o PhoneIn
+        \row \o Travel
+        \row \o Leisure
+        \row \o JazzMusic
+        \row \o CountryMusic
+        \row \o NationalMusic
+        \row \o OldiesMusic
+        \row \o FolkMusic
+        \row \o Documentary
+        \row \o AlarmTest
+        \row \o Alarm
+        \row \o Talk
+        \row \o ClassicRock
+        \row \o AdultHits
+        \row \o SoftRock
+        \row \o Top40
+        \row \o Soft
+        \row \o Nostalgia
+        \row \o Classical
+        \row \o RhythmAndBlues
+        \row \o SoftRhythmAndBlues
+        \row \o Language
+        \row \o ReligiousMusic
+        \row \o ReligiousTalk
+        \row \o Personality
+        \row \o Public
+        \row \o College
+
+    \endtable
+  */
 QDeclarativeRadioData::ProgramType QDeclarativeRadioData::programType() const
 {
     return static_cast<QDeclarativeRadioData::ProgramType>(m_radioData->programType());
 }
 
+/*!
+    \qmlproperty string RadioData::programTypeName
+
+    This property holds a string representation of the \l programType.
+  */
 QString QDeclarativeRadioData::programTypeName() const
 {
     return m_radioData->programTypeName();
 }
 
+/*!
+    \qmlproperty string RadioData::stationName
+
+    This property has the name of the currently tuned radio station.
+  */
 QString QDeclarativeRadioData::stationName() const
 {
     return m_radioData->stationName();
 }
 
+/*!
+    \qmlproperty string RadioData::radioText
+
+    This property holds free-text transmitted by the radio station. This is typically used to
+    show supporting information for the currently playing content, for instance song title or
+    artist name.
+  */
 QString QDeclarativeRadioData::radioText() const
 {
     return m_radioData->radioText();
 }
 
+/*!
+    \qmlproperty bool RadioData::alternativeFrequenciesEnabled
+
+    This property allows you to specify whether the radio should try and tune to alternative
+    frequencies if the signal strength of the current station becomes too weak. The alternative
+    frequencies are emitted over RDS by the radio station, and the tuning happens automatically.
+  */
 bool QDeclarativeRadioData::alternativeFrequenciesEnabled() const
 {
     return m_radioData->isAlternativeFrequenciesEnabled();