Minor doc fixes for QML

renaming QML element to QML type
removing some \fn tags that were making the docs not build
some rewording
some new signal docs

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

8 files changed, 84 insertions, 60 deletions

diff --git a/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp b/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp
index 4d2fca3a3..e1a4ac004 100644
--- a/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp
+++ b/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp
@@ -92,16 +92,15 @@ void QDeclarativeAttenuationModel::setName(const QString& name)
 /*!
     \qmlclass AttenuationModelLinear QDeclarativeAttenuationModelLinear
     \since 5.0
-    \brief The AttenuationModelLinear element allows you to define a linear attenuation curve for
-    Sound element.
+    \brief Defines a linear attenuation curve for a \l Sound.
     \inqmlmodule QtAudioEngine 1
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    This type is part of the \b{QtAudioEngine 1.0} module.
 
-    AttenuationModelLinear must be defined inside AudioEngine.
+    AttenuationModelLinear must be defined inside \l AudioEngine.
 
     \qml
     import QtQuick 2.0
@@ -224,14 +223,13 @@ qreal QDeclarativeAttenuationModelLinear::calculateGain(const QVector3D &listene
 /*!
     \qmlclass AttenuationModelInverse QDeclarativeAttenuationModelInverse
     \since 5.0
-    \brief The AttenuationModelInverse element allows you to define a non-linear attenuation curve
-    for Sound element.
+    \brief Defines a non-linear attenuation curve for a \l Sound.
     \inmodule QtMultimedia
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    This type is part of the \b{QtAudioEngine 1.0} module.
 
     AttenuationModelInverse must be defined inside AudioEngine.
 
diff --git a/src/imports/audioengine/qdeclarative_audiocategory_p.cpp b/src/imports/audioengine/qdeclarative_audiocategory_p.cpp
index e34541728..1c78bd8bd 100644
--- a/src/imports/audioengine/qdeclarative_audiocategory_p.cpp
+++ b/src/imports/audioengine/qdeclarative_audiocategory_p.cpp
@@ -49,15 +49,15 @@ QT_USE_NAMESPACE
 /*!
     \qmlclass AudioCategory QDeclarativeAudioCategory
     \since 5.0
-    \brief The AudioCategory element allows you to control all active sound instances by group
+    \brief Control all active sound instances by group.
     \inqmlmodule QtAudioEngine 1
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    This type is part of the \b{QtAudioEngine 1.0} module.
 
-    AudioCategory element can be accessed through QtAudioEngine1::AudioEngine::categories with its
+    An instance of AudioCategory can be accessed through QtAudioEngine1::AudioEngine::categories with its
     unique name and must be defined inside AudioEngine.
 
     \qml
@@ -100,11 +100,11 @@ QT_USE_NAMESPACE
     }
     \endqml
 
-    Sound elements can be grouped togather by specifying the category property. When you change the
-    volume of a category, all audio output from related elements will be affected as well.
+    \l Sound instances can be grouped together by specifying the category property. When you change the
+    volume of a category, all audio output from related instances will be affected as well.
 
     Note: there will always be an AudioCategory named \c default whether you explicitly define it or
-    not. If you do not specify any category for a Sound element, it will be grouped into the \c default
+    not. If you do not specify any category for a \l Sound, it will be grouped into the \c default
     category.
 
 */
@@ -140,7 +140,7 @@ void QDeclarativeAudioCategory::componentComplete()
     \qmlproperty real QtAudioEngine1::AudioCategory::volume
 
     This property holds the volume of the category and will modulate all audio output from the
-    element which belongs to this category.
+    instances which belong to this category.
 */
 qreal QDeclarativeAudioCategory::volume() const
 {
@@ -162,7 +162,7 @@ void QDeclarativeAudioCategory::setVolume(qreal volume)
     \qmlproperty string QtAudioEngine1::AudioCategory::name
 
     This property holds the name of AudioCategory. The name must be unique among all categories and only
-    defined once.
+    defined once. The name cannot be changed after the instance has been initialized.
 */
 void QDeclarativeAudioCategory::setName(const QString& name)
 {
diff --git a/src/imports/audioengine/qdeclarative_audioengine_p.cpp b/src/imports/audioengine/qdeclarative_audioengine_p.cpp
index dce97f87e..fa7c1919c 100644
--- a/src/imports/audioengine/qdeclarative_audioengine_p.cpp
+++ b/src/imports/audioengine/qdeclarative_audioengine_p.cpp
@@ -58,13 +58,13 @@ QT_USE_NAMESPACE
 /*!
     \qmlclass AudioEngine QDeclarativeAudioEngine
     \since 5.0
-    \brief The AudioEngine element allows you to organize all your 3d audio content in one place.
+    \brief The AudioEngine type allows you to organize all your 3d audio content in one place.
     \inqmlmodule QtAudioEngine 1
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    \c AudioEngine is part of the \b{QtAudioEngine 1.0} module.
 
     \qml
     import QtQuick 2.0
@@ -91,7 +91,7 @@ QT_USE_NAMESPACE
             }
 
             dopplerFactor: 1
-            speedOfSound: 343.33
+            speedOfSound: 343.33 // Approximate speed of sound in air at 20 degrees Celsius
 
             listener.up:"0,0,1"
             listener.position:"0,0,0"
@@ -108,10 +108,10 @@ QT_USE_NAMESPACE
     }
     \endqml
 
-    The \c AudioEngine element acts as a central library for configuring all 3d audio content in an
-    app, so you should define only one such element in your app.
+    \c AudioEngine acts as a central library for configuring all 3d audio content in an
+    app, so you should define only one in your app.
 
-    It is mostly used as a container to access other elements such as AudioCategory, AudioSample and
+    It is mostly used as a container to access other types such as AudioCategory, AudioSample and
     Sound.
 
     \sa AudioCategory, AudioSample, Sound, SoundInstance, AttenuationModelLinear, AttenuationModelInverse
@@ -409,7 +409,7 @@ QQmlListProperty<QObject> QDeclarativeAudioEngine::bank()
 /*!
     \qmlproperty map QtAudioEngine1::AudioEngine::categories
 
-    Container of all AudioCategory elements.
+    Container of all AudioCategory instances.
 */
 QObject* QDeclarativeAudioEngine::categories()
 {
@@ -419,7 +419,7 @@ QObject* QDeclarativeAudioEngine::categories()
 /*!
     \qmlproperty map QtAudioEngine1::AudioEngine::samples
 
-    Container of all AudioSample elements.
+    Container of all AudioSample instances.
 */
 QObject* QDeclarativeAudioEngine::samples()
 {
@@ -429,7 +429,7 @@ QObject* QDeclarativeAudioEngine::samples()
 /*!
     \qmlproperty map QtAudioEngine1::AudioEngine::sounds
 
-    Container of all Sound elements.
+    Container of all Sound instances.
 */
 QObject* QDeclarativeAudioEngine::sounds()
 {
@@ -467,8 +467,11 @@ void QDeclarativeAudioEngine::setDopplerFactor(qreal dopplerFactor)
 /*!
     \qmlproperty real QtAudioEngine1::AudioEngine::speedOfSound
 
-    This property holds the reference value of the sound speed which will be used in doppler shift
-    calculation.
+    This property holds the reference value of the sound speed (in meters per second)
+    which will be used in doppler shift calculation. The doppler shift calculation is
+    used to emulate the change in frequency in sound that is perceived by an observer when
+    the sound source is travelling towards or away from the observer. The speed of sound
+    depends on the medium the sound is propagating through.
 */
 qreal QDeclarativeAudioEngine::speedOfSound() const
 {
@@ -481,7 +484,7 @@ void QDeclarativeAudioEngine::setSpeedOfSound(qreal speedOfSound)
 }
 
 /*!
-    \qmlproperty real QtAudioEngine1::AudioEngine::loading
+    \qmlproperty bool QtAudioEngine1::AudioEngine::loading
 
     This property indicates if the audio engine is loading any audio sample at the moment. This may
     be useful if you specified the preloaded property in AudioSample and would like to show a loading screen
@@ -501,21 +504,38 @@ void QDeclarativeAudioEngine::handleLoadingChanged()
 }
 
 /*!
-    \qmlsignal QtAudioEngine1::AudioEngine::onLiveInstancesChanged()
+    \qmlsignal QtAudioEngine1::AudioEngine::finishedLoading()
+
+    This signal is emitted when \l loading has completed.
 
-    This handler is called when \l liveInstances is changed
+    The corresponding handler is \c onFinishedLoading.
 */
 
 /*!
-    \qmlsignal QtAudioEngine1::AudioEngine::onLoadingChanged()
+    \qmlsignal QtAudioEngine1::AudioEngine::ready()
+
+    This signal is emitted when the AudioEngine is ready to use.
 
-    This handler is called when \l loading is changed
+    The corresponding handler is \c onReady.
 */
 
 /*!
-    \qmlsignal QtAudioEngine1::AudioEngine::finishedLoading()
+    \qmlsignal QtAudioEngine1::AudioEngine::liveInstanceCountChanged()
+
+    This signal is emitted when the number of live instances managed by the
+    AudioEngine is changed.
+
+    The corresponding handler is \c onLiveInstanceCountChanged.
+*/
+
+/*!
+    \qmlsignal QtAudioEngine1::AudioEngine::isLoadingChanged()
 
-    This handler is called when \l loading is finished
+    This signal is emitted when the \l loading property changes.
+
+    The corresponding handler is \c onIsLoadingChanged.
 */
+
+
 QT_END_NAMESPACE
 
diff --git a/src/imports/audioengine/qdeclarative_audiolistener_p.cpp b/src/imports/audioengine/qdeclarative_audiolistener_p.cpp
index ea269053a..77851332b 100644
--- a/src/imports/audioengine/qdeclarative_audiolistener_p.cpp
+++ b/src/imports/audioengine/qdeclarative_audiolistener_p.cpp
@@ -50,13 +50,13 @@ QT_USE_NAMESPACE
 /*!
     \qmlclass AudioListener QDeclarativeAudioListener
     \since 5.0
-    \brief The AudioListener element allows you to control global listener parameters.
+    \brief The AudioListener type allows you to control global listener parameters.
     \inqmlmodule QtAudioEngine 1
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    This type is part of the \b{QtAudioEngine 1.0} module.
 
     AudioListener will have only one global instance and you can either access it through the
     listener property of AudioEngine:
@@ -97,7 +97,7 @@ QT_USE_NAMESPACE
     }
     \endqml
 
-    or alternatively, by defining an AudioListener element outside AudioEngine:
+    or alternatively, by defining an AudioListener outside AudioEngine:
 
     \qml
     import QtQuick 2.0
@@ -248,7 +248,7 @@ void QDeclarativeAudioListener::setUp(const QVector3D &up)
 /*!
     \qmlproperty real QtAudioEngine1::AudioListener::gain
 
-    This property will modulate all audio output from audio engine elements.
+    This property will modulate all audio output from audio engine instances.
 */
 qreal QDeclarativeAudioListener::gain() const
 {
diff --git a/src/imports/audioengine/qdeclarative_audiosample_p.cpp b/src/imports/audioengine/qdeclarative_audiosample_p.cpp
index 6a33e86a5..fe80989ee 100644
--- a/src/imports/audioengine/qdeclarative_audiosample_p.cpp
+++ b/src/imports/audioengine/qdeclarative_audiosample_p.cpp
@@ -52,15 +52,15 @@ QT_USE_NAMESPACE
 /*!
     \qmlclass AudioSample QDeclarativeAudioSample
     \since 5.0
-    \brief The AudioSample element allows you to load audio samples, mostly wav file.
+    \brief The AudioSample type allows you to load audio samples, mostly wav file.
     \inqmlmodule QtAudioEngine 1
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    \c AudioSample is part of the \b{QtAudioEngine 1.0} module.
 
-    AudioSample element can be accessed through QtAudioEngine1::AudioEngine::samples with its unique
+    It can be accessed through QtAudioEngine1::AudioEngine::samples with its unique
     name and must be defined inside AudioEngine.
 
     \qml
@@ -135,9 +135,9 @@ bool QDeclarativeAudioSample::isStreaming() const
 /*!
     \qmlproperty bool QtAudioEngine1::AudioSample::preloaded
 
-    This property holds indicates whether this sample needs to be preloaded or not.
+    This property indicates whether this sample needs to be preloaded or not.
     If true, the audio engine will start loading the sample file immediately when the app started,
-    otherwise the sample will not be loaded untill be used by other element.
+    otherwise the sample will not be loaded until explicitly requested.
 */
 
 bool QDeclarativeAudioSample::isPreloaded() const
diff --git a/src/imports/audioengine/qdeclarative_playvariation_p.cpp b/src/imports/audioengine/qdeclarative_playvariation_p.cpp
index f46170689..fd6456a0a 100644
--- a/src/imports/audioengine/qdeclarative_playvariation_p.cpp
+++ b/src/imports/audioengine/qdeclarative_playvariation_p.cpp
@@ -51,7 +51,7 @@ QT_USE_NAMESPACE
 /*!
     \qmlclass PlayVariation QDeclarativePlayVariation
     \since 5.0
-    \brief The PlayVariation element allows you to define a playback variation for \l Sound element.
+    \brief The PlayVariation type allows you to define a playback variation for \l {Sound} {sounds}.
     So each time the playback of the same sound can be a slightly different even with the same
     AudioSample.
 
@@ -60,9 +60,9 @@ QT_USE_NAMESPACE
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    This type is part of the \b{QtAudioEngine 1.0} module.
 
-    PlayVariation must be defined inside \l Sound element.
+    PlayVariation must be defined inside a \l Sound.
 
     \qml
     import QtQuick 2.0
diff --git a/src/imports/audioengine/qdeclarative_sound_p.cpp b/src/imports/audioengine/qdeclarative_sound_p.cpp
index 5b333c22d..e775d1dbb 100644
--- a/src/imports/audioengine/qdeclarative_sound_p.cpp
+++ b/src/imports/audioengine/qdeclarative_sound_p.cpp
@@ -140,16 +140,16 @@ void QDeclarativeSoundCone::componentComplete()
 /*!
     \qmlclass Sound QDeclarativeSound
     \since 5.0
-    \brief The Sound element allows you to define a variety of samples and parameters to be used for
+    \brief The Sound type allows you to define a variety of samples and parameters to be used for
     SoundInstance.
     \inqmlmodule QtAudioEngine 1
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    This type is part of the \b{QtAudioEngine 1.0} module.
 
-    Sound element can be accessed through QtAudioEngine1::AudioEngine::sounds with its unique name
+    Sound can be accessed through QtAudioEngine1::AudioEngine::sounds with its unique name
     and must be defined inside AudioEngine.
 
     \qml
@@ -227,7 +227,7 @@ void QDeclarativeSound::componentComplete()
 }
 
 /*!
-    \qmlproperty enueration QtAudioEngine1::Sound::playType
+    \qmlproperty enumeration QtAudioEngine1::Sound::playType
 
     This property holds the playType.  It can be one of:
 
diff --git a/src/imports/audioengine/qdeclarative_soundinstance_p.cpp b/src/imports/audioengine/qdeclarative_soundinstance_p.cpp
index 7b852d95d..b5763df14 100644
--- a/src/imports/audioengine/qdeclarative_soundinstance_p.cpp
+++ b/src/imports/audioengine/qdeclarative_soundinstance_p.cpp
@@ -53,16 +53,16 @@ QT_USE_NAMESPACE
 /*!
     \qmlclass SoundInstance QDeclarativeSoundInstance
     \since 5.0
-    \brief The SoundInstance element allows you to play 3d audio content.
+    \brief The SoundInstance type allows you to play 3d audio content.
     \inqmlmodule QtAudioEngine 1
     \ingroup multimedia_audioengine
     \inherits Item
     \preliminary
 
-    This element is part of the \b{QtAudioEngine 1.0} module.
+    This type is part of the \b{QtAudioEngine 1.0} module.
 
     There are two ways to create SoundInstance objects. You can obtain it by calling newInstance
-    method of Sound element:
+    method of a \l Sound:
 
     \qml
     import QtQuick 2.0
@@ -101,7 +101,7 @@ QT_USE_NAMESPACE
     }
     \endqml
 
-    Or alternatively, you can explicitly define SoundInstance element outside of AudioEngine for
+    Or alternatively, you can explicitly define SoundInstance outside of AudioEngine for
     easier qml bindings:
 
     \qml
@@ -236,7 +236,7 @@ QDeclarativeSoundInstance::~QDeclarativeSoundInstance()
     \qmlproperty string QtAudioEngine1::SoundInstance::sound
 
     This property specifies which Sound this SoundInstance will use. Unlike some properties in
-    other elements, this property can be changed dynamically.
+    other types, this property can be changed dynamically.
 */
 QString QDeclarativeSoundInstance::sound() const
 {
@@ -258,7 +258,7 @@ void QDeclarativeSoundInstance::setSound(const QString& sound)
     }
 
 #ifdef DEBUG_AUDIOENGINE
-    qDebug() << "SoundInstance Element switch sound from [" << m_sound << "] to [" << sound << "]";
+    qDebug() << "SoundInstance switch sound from [" << m_sound << "] to [" << sound << "]";
 #endif
 
     stop();
@@ -297,11 +297,17 @@ void QDeclarativeSoundInstance::dropInstance()
 
     This property holds the current playback state. It can be one of:
 
-    \list
-    \li StopppedState
-    \li PlayingState
-    \li PausedState
-    \endlist
+    \table
+    \header \li Value \li Description
+    \row \li StopppedState
+        \li The SoundInstance is not playing, and when playback begins next it
+        will play from position zero.
+    \row \li PlayingState
+        \li The SoundInstance is playing the media.
+    \row \li PausedState
+        \li The SoundInstance is not playing, and when playback begins next it
+        will play from the position that it was paused at.
+    \endtable
 */
 QDeclarativeSoundInstance::State QDeclarativeSoundInstance::state() const
 {