Improve audio volume documentation

Added information about volume scales.

Change-Id: Ica8367396147e3e1c814b3575faa5cf0503be031
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Christian Stromme <christian.stromme@qt.io>

9 files changed, 94 insertions, 16 deletions

diff --git a/src/imports/multimedia/Video.qml b/src/imports/multimedia/Video.qml
index 2188d17b9..b3fee7495 100644
--- a/src/imports/multimedia/Video.qml
+++ b/src/imports/multimedia/Video.qml
@@ -360,7 +360,17 @@ Item {
     /*!
         \qmlproperty real Video::volume
 
-        This property holds the volume of the audio output, from 0.0 (silent) to 1.0 (maximum volume).
+        This property holds the audio volume.
+
+        The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside
+        this range will be clamped.
+
+        The default volume is \c 1.0.
+
+        UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic
+        scale will produce linear changes in perceived loudness, which is what a user would normally
+        expect from a volume control. See \l {QtMultimedia::QtMultimedia::convertVolume()}{QtMultimedia.convertVolume()}
+        for more details.
     */
     property alias volume:          player.volume
 
diff --git a/src/imports/multimedia/qdeclarativeaudio.cpp b/src/imports/multimedia/qdeclarativeaudio.cpp
index 86f8f30ba..5a065072c 100644
--- a/src/imports/multimedia/qdeclarativeaudio.cpp
+++ b/src/imports/multimedia/qdeclarativeaudio.cpp
@@ -689,9 +689,17 @@ QDeclarativeAudio::PlaybackState QDeclarativeAudio::playbackState() const
 /*!
     \qmlproperty real QtMultimedia::Audio::volume
 
-    This property holds the volume of the audio output, from 0.0 (silent) to 1.0 (maximum volume).
+    This property holds the audio volume.
 
-    Defaults to 1.0.
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See \l {QtMultimedia::QtMultimedia::convertVolume()}{QtMultimedia.convertVolume()}
+    for more details.
 */
 
 /*!
@@ -1310,9 +1318,17 @@ void QDeclarativeAudio::_q_mediaChanged(const QMediaContent &media)
 /*!
     \qmlproperty real QtMultimedia::MediaPlayer::volume
 
-    This property holds the volume of the audio output, from 0.0 (silent) to 1.0 (maximum volume).
+    This property holds the audio volume of the media player.
 
-    Defaults to 1.0.
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See \l {QtMultimedia::QtMultimedia::convertVolume()}{QtMultimedia.convertVolume()}
+    for more details.
 */
 
 /*!
diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index bc6b6215b..ad54521fa 100644
--- a/src/multimedia/audio/qaudioinput.cpp
+++ b/src/multimedia/audio/qaudioinput.cpp
@@ -330,10 +330,15 @@ int QAudioInput::notifyInterval() const
 /*!
     Sets the input volume to \a volume.
 
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
     If the device does not support adjusting the input
     volume then \a volume will be ignored and the input
     volume will remain at 1.0.
 
+    The default volume is \c 1.0.
+
     Note: Adjustments to the volume will change the volume of this audio stream, not the global volume.
 */
 void QAudioInput::setVolume(qreal volume)
@@ -342,7 +347,7 @@ void QAudioInput::setVolume(qreal volume)
 }
 
 /*!
-    Returns the input volume (gain).
+    Returns the input volume.
 
     If the device does not support adjusting the input volume
     the returned value will be 1.0.
diff --git a/src/multimedia/audio/qaudiooutput.cpp b/src/multimedia/audio/qaudiooutput.cpp
index 585855ace..670dca7bc 100644
--- a/src/multimedia/audio/qaudiooutput.cpp
+++ b/src/multimedia/audio/qaudiooutput.cpp
@@ -349,9 +349,18 @@ QAudio::State QAudioOutput::state() const
 }
 
 /*!
-    Sets the volume.
-    Where \a volume is between 0.0 and 1.0 inclusive.
+    Sets the output volume to \a volume.
+
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
     Note: Adjustments to the volume will change the volume of this audio stream, not the global volume.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See QAudio::convertVolume() for more details.
 */
 void QAudioOutput::setVolume(qreal volume)
 {
diff --git a/src/multimedia/audio/qsoundeffect.cpp b/src/multimedia/audio/qsoundeffect.cpp
index f653de86e..d3b818073 100644
--- a/src/multimedia/audio/qsoundeffect.cpp
+++ b/src/multimedia/audio/qsoundeffect.cpp
@@ -258,12 +258,22 @@ int QSoundEffect::loopsRemaining() const
 /*!
     \qmlproperty qreal QtMultimedia::SoundEffect::volume
 
-    This property holds the volume of the sound effect playback, from 0.0 (silent) to 1.0 (maximum volume).
+    This property holds the volume of the sound effect playback.
+
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See \l {QtMultimedia::QtMultimedia::convertVolume()}{QtMultimedia.convertVolume()}
+    for more details.
 */
 /*!
     \property QSoundEffect::volume
 
-    This property holds the volume of the sound effect playback, from 0.0 (silent) to 1.0 (maximum volume).
+    This property holds the volume of the sound effect playback, from 0.0 (silence) to 1.0 (full volume).
 */
 
 /*!
@@ -275,7 +285,16 @@ qreal QSoundEffect::volume() const
 }
 
 /*!
-    Sets the volume to play the sound effect at to \a volume, from 0.0 (silent) to 1.0 (maximum volume).
+    Sets the sound effect volume to \a volume.
+
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See QAudio::convertVolume() for more details.
  */
 void QSoundEffect::setVolume(qreal volume)
 {
diff --git a/src/multimedia/controls/qmediaplayercontrol.cpp b/src/multimedia/controls/qmediaplayercontrol.cpp
index cd56dffcb..46de05b51 100644
--- a/src/multimedia/controls/qmediaplayercontrol.cpp
+++ b/src/multimedia/controls/qmediaplayercontrol.cpp
@@ -175,6 +175,8 @@ QMediaPlayerControl::QMediaPlayerControl(QObject *parent):
     \fn QMediaPlayerControl::setVolume(int volume)
 
     Sets the audio \a volume of a player control.
+
+    The volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
 */
 
 /*!
diff --git a/src/multimedia/controls/qmediarecordercontrol.cpp b/src/multimedia/controls/qmediarecordercontrol.cpp
index 4654d16eb..611f1fdcc 100644
--- a/src/multimedia/controls/qmediarecordercontrol.cpp
+++ b/src/multimedia/controls/qmediarecordercontrol.cpp
@@ -160,13 +160,15 @@ QMediaRecorderControl::~QMediaRecorderControl()
 /*!
     \fn qreal QMediaRecorderControl::volume() const
 
-    Returns the linear audio gain of media recorder.
+    Returns the audio volume of a media recorder control.
 */
 
 /*!
     \fn void QMediaRecorderControl::setVolume(qreal gain)
 
-    Sets the linear audio \a gain of a media recorder.
+    Sets the audio \a volume of a media recorder control.
+
+    The volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
 */
 
 /*!
diff --git a/src/multimedia/playback/qmediaplayer.cpp b/src/multimedia/playback/qmediaplayer.cpp
index c5261921a..648c13220 100644
--- a/src/multimedia/playback/qmediaplayer.cpp
+++ b/src/multimedia/playback/qmediaplayer.cpp
@@ -1372,8 +1372,14 @@ QList<QAudio::Role> QMediaPlayer::supportedAudioRoles() const
     \property QMediaPlayer::volume
     \brief the current playback volume.
 
-    The playback volume is linear in effect and the value can range from 0 -
-    100, values outside this range will be clamped.
+    The playback volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
+    Values outside this range will be clamped.
+
+    By default the volume is \c 100.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See QAudio::convertVolume() for more details.
 */
 
 /*!
diff --git a/src/multimedia/recording/qmediarecorder.cpp b/src/multimedia/recording/qmediarecorder.cpp
index a5f4c15ce..7b0234988 100644
--- a/src/multimedia/recording/qmediarecorder.cpp
+++ b/src/multimedia/recording/qmediarecorder.cpp
@@ -556,7 +556,16 @@ void QMediaRecorder::setMuted(bool muted)
 /*!
     \property QMediaRecorder::volume
 
-    \brief the linear audio gain of media recorder.
+    \brief the current recording audio volume.
+
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See QAudio::convertVolume() for more details.
 */
 
 qreal QMediaRecorder::volume() const