Doc: Fix qdoc warnings for undocumented members in QAudio*

In addition, fixed a few clang-format warnings.

Pick-to: 6.4
Change-Id: I9d97f1e7e2454e524229d5621ee9461558049830
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>

9 files changed, 160 insertions, 60 deletions

diff --git a/src/multimedia/audio/qaudiobuffer.cpp b/src/multimedia/audio/qaudiobuffer.cpp
index 08c89769f..692da6282 100644
--- a/src/multimedia/audio/qaudiobuffer.cpp
+++ b/src/multimedia/audio/qaudiobuffer.cpp
@@ -12,9 +12,7 @@ class QAudioBufferPrivate : public QSharedData
 {
 public:
     QAudioBufferPrivate(const QAudioFormat &f, const QByteArray &d, qint64 start)
-        : format(f),
-        data(d),
-        startTime(start)
+        : format(f), data(d), startTime(start)
     {
     }
 
@@ -35,11 +33,12 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QAudioBufferPrivate);
     \inmodule QtMultimedia
     \ingroup multimedia
     \ingroup multimedia_audio
-    \brief The QAudioBuffer class represents a collection of audio samples with a specific format and sample rate.
+    \brief The QAudioBuffer class represents a collection of audio samples with a specific format
+   and sample rate.
 
-    QAudioBuffer is used by the QAudioDecoder class to hand decoded audio data over to the application. An audio buffer
-    contains data in a certain QAudioFormat that can be queried using format(). It is also tagged with timing and duration
-    information.
+    QAudioBuffer is used by the QAudioDecoder class to hand decoded audio data over to the
+   application. An audio buffer contains data in a certain QAudioFormat that can be queried using
+   format(). It is also tagged with timing and duration information.
 
     To access the data stored inside the buffer, use the data() or constData() methods.
 
@@ -104,6 +103,12 @@ QAudioBuffer::QAudioBuffer(int numFrames, const QAudioFormat &format, qint64 sta
 */
 
 /*!
+   \fn void QAudioBuffer::swap(QAudioBuffer &other) noexcept
+
+   Swaps the audio buffer with \a other.
+*/
+
+/*!
     \fn QAudioBuffer &QAudioBuffer::operator=(QAudioBuffer &&other)
 
     Moves \a other into this QAudioBuffer.
@@ -112,7 +117,7 @@ QAudioBuffer::QAudioBuffer(int numFrames, const QAudioFormat &format, qint64 sta
 /*!
     Assigns the \a other buffer to this.
  */
-QAudioBuffer &QAudioBuffer::operator =(const QAudioBuffer &other) = default;
+QAudioBuffer &QAudioBuffer::operator=(const QAudioBuffer &other) = default;
 
 /*!
     Destroys this audio buffer.
@@ -225,7 +230,7 @@ qint64 QAudioBuffer::startTime() const noexcept
     \endcode
 
 */
-const void* QAudioBuffer::constData() const noexcept
+const void *QAudioBuffer::constData() const noexcept
 {
     if (!d)
         return nullptr;
@@ -248,14 +253,13 @@ const void* QAudioBuffer::constData() const noexcept
     const quint16 *data = buffer->data<quint16>();
     \endcode
 */
-const void* QAudioBuffer::data() const noexcept
+const void *QAudioBuffer::data() const noexcept
 {
     if (!d)
         return nullptr;
     return d->data.constData();
 }
 
-
 /*
     Template data/constData functions caused override problems with qdoc,
     so moved their docs into the non template versions.
@@ -292,4 +296,33 @@ void *QAudioBuffer::data()
     channel is a \e {signed short}.
 */
 
+/*!
+    \typedef QAudioBuffer::U8M
+
+    This is a predefined specialization for an unsigned 8 bit mono sample.
+*/
+/*!
+    \typedef QAudioBuffer::S16M
+    This is a predefined specialization for a signed 16 bit mono sample.
+i*/
+/*!
+    \typedef QAudioBuffer::S32M
+    This is a predefined specialization for a signed 32 bit mono sample.
+*/
+/*!
+    \typedef QAudioBuffer::F32M
+    This is a predefined specialization for a 32 bit float mono sample.
+*/
+/*!
+    \typedef QAudioBuffer::U8S
+    This is a predifined specialization for an unsiged 8 bit stereo sample.
+*/
+/*!
+    \typedef QAudioBuffer::S32S
+    This is a predifined specialization for a siged 32 bit stereo sample.
+*/
+/*!
+    \typedef QAudioBuffer::F32S
+    This is a predifined specialization for a 32 bit float stereo sample.
+*/
 QT_END_NAMESPACE
diff --git a/src/multimedia/audio/qaudiodecoder.cpp b/src/multimedia/audio/qaudiodecoder.cpp
index 015ecb2de..088852f5c 100644
--- a/src/multimedia/audio/qaudiodecoder.cpp
+++ b/src/multimedia/audio/qaudiodecoder.cpp
@@ -73,8 +73,8 @@ bool QAudioDecoder::isDecoding() const
 }
 
 /*!
-    \property QAudioDecoder::error
-    \brief The current error state.
+
+    Returns the current error state of the QAudioDecoder.
 */
 QAudioDecoder::Error QAudioDecoder::error() const
 {
@@ -82,6 +82,8 @@ QAudioDecoder::Error QAudioDecoder::error() const
 }
 
 /*!
+    \property QAudioDecoder::error
+
     Returns a human readable description of the current error, or
     an empty string is there is no error.
 */
@@ -276,7 +278,7 @@ QAudioBuffer QAudioDecoder::read() const
 
 // Signals
 /*!
-    \fn QAudioDecoder::error(QAudioDecoder::Error error)
+    \fn void QAudioDecoder::error(QAudioDecoder::Error error)
 
     Signals that an \a error condition has occurred.
 
diff --git a/src/multimedia/audio/qaudiodevice.cpp b/src/multimedia/audio/qaudiodevice.cpp
index 507d17a57..54a21f20e 100644
--- a/src/multimedia/audio/qaudiodevice.cpp
+++ b/src/multimedia/audio/qaudiodevice.cpp
@@ -16,12 +16,14 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QAudioDevicePrivate);
 
 /*!
     \class QAudioDevice
-    \brief The QAudioDevice class provides an information about audio devices and their functionality.
+    \brief The QAudioDevice class provides an information about audio devices and their
+           functionality.
     \inmodule QtMultimedia
     \ingroup multimedia
     \ingroup multimedia_audio
 
-    QAudioDevice describes an audio device available in the system, either for input or for playback.
+    QAudioDevice describes an audio device available in the system, either for input or for
+    playback.
 
     A QAudioDevice is used by Qt to construct
     classes that communicate with the device -- such as
@@ -51,7 +53,7 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QAudioDevicePrivate);
     sound, i.e., play an audio stream in a supported format. For each device we
     find, we simply print the deviceName().
 
-    \sa QAudioSink, QAudioSource QAudioFormat
+    \sa QAudioSink,QAudioSource,QAudioFormat
 */
 
 /*!
@@ -91,14 +93,18 @@ QAudioDevice::QAudioDevice() = default;
 /*!
     Constructs a copy of \a other.
 */
-QAudioDevice::QAudioDevice(const QAudioDevice& other) = default;
+QAudioDevice::QAudioDevice(const QAudioDevice &other) = default;
 
 /*!
     \fn QAudioDevice::QAudioDevice(QAudioDevice &&other)
 
     Move constructs from \a other.
 */
+/*!
+    \fn void QAudioDevice::swap(QAudioDevice &other) noexcept
 
+    Swaps the audio device with the \a other.
+*/
 /*!
     Destroy this audio device info.
 */
@@ -107,7 +113,7 @@ QAudioDevice::~QAudioDevice() = default;
 /*!
     Sets the QAudioDevice object to be equal to \a other.
 */
-QAudioDevice& QAudioDevice::operator=(const QAudioDevice &other) = default;
+QAudioDevice &QAudioDevice::operator=(const QAudioDevice &other) = default;
 
 /*!
     \fn QAudioDevice& QAudioDevice::operator=(QAudioDevice &&other)
@@ -119,7 +125,7 @@ QAudioDevice& QAudioDevice::operator=(const QAudioDevice &other) = default;
     Returns true if this QAudioDevice class represents the
     same audio device as \a other.
 */
-bool QAudioDevice::operator ==(const QAudioDevice &other) const
+bool QAudioDevice::operator==(const QAudioDevice &other) const
 {
     if (d == other.d)
         return true;
@@ -134,7 +140,7 @@ bool QAudioDevice::operator ==(const QAudioDevice &other) const
     Returns true if this QAudioDevice class represents a
     different audio device than \a other
 */
-bool QAudioDevice::operator !=(const QAudioDevice &other) const
+bool QAudioDevice::operator!=(const QAudioDevice &other) const
 {
     return !operator==(other);
 }
@@ -158,6 +164,8 @@ bool QAudioDevice::isNull() const
 */
 
 /*!
+    \property QAudioDevice::id
+
     Returns an identifier for the audio device.
 
     Device names vary depending on the platform/audio plugin being used.
@@ -178,6 +186,8 @@ QByteArray QAudioDevice::id() const
 */
 
 /*!
+    \property QAudioDevice::description
+
     Returns a human readable name of the audio device.
 
     Use this string to present the device to the user.
@@ -194,6 +204,8 @@ QString QAudioDevice::description() const
 */
 
 /*!
+    \property QAudioDevice::isDefault
+
     Returns true if this is the default audio device.
 */
 bool QAudioDevice::isDefault() const
@@ -209,9 +221,11 @@ bool QAudioDevice::isFormatSupported(const QAudioFormat &settings) const
 {
     if (isNull())
         return false;
-    if (settings.sampleRate() < d->minimumSampleRate || settings.sampleRate() > d->maximumSampleRate)
+    if (settings.sampleRate() < d->minimumSampleRate
+        || settings.sampleRate() > d->maximumSampleRate)
         return false;
-    if (settings.channelCount() < d->minimumChannelCount || settings.channelCount() > d->maximumChannelCount)
+    if (settings.channelCount() < d->minimumChannelCount
+        || settings.channelCount() > d->maximumChannelCount)
         return false;
     if (!d->supportedSampleFormats.contains(settings.sampleFormat()))
         return false;
@@ -289,11 +303,13 @@ QAudioFormat::ChannelConfig QAudioDevice::channelConfiguration() const
 }
 
 /*!
+    \fn QAudioDevicePrivate QAudioDevice::handle() const
     \internal
 */
-QAudioDevice::QAudioDevice(QAudioDevicePrivate *p)
-    : d(p)
-{}
+/*!
+    \internal
+*/
+QAudioDevice::QAudioDevice(QAudioDevicePrivate *p) : d(p) { }
 
 /*!
     \enum QAudioDevice::Mode
@@ -323,7 +339,9 @@ QAudioDevice::QAudioDevice(QAudioDevicePrivate *p)
 */
 
 /*!
-    returns whether this device is an input or output device.
+    \property QAudioDevice::mode
+
+    Returns whether this device is an input or output device.
 */
 QAudioDevice::Mode QAudioDevice::mode() const
 {
diff --git a/src/multimedia/audio/qaudioformat.cpp b/src/multimedia/audio/qaudioformat.cpp
index f88ad1478..a53dd8cc1 100644
--- a/src/multimedia/audio/qaudioformat.cpp
+++ b/src/multimedia/audio/qaudioformat.cpp
@@ -81,9 +81,15 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QAudioFormat& QAudioFormat::operator=(const QAudioFormat &other)
+    \fn bool QAudioFormat::operator==(const QAudioFormat &a, const QAudioFormat &b)
 
-    Assigns \a other to this QAudioFormat implementation.
+    Returns \c true if audio format \a a is equal to \a b, otherwise returns \c false.
+*/
+
+/*!
+    \fn bool QAudioFormat::operator!=(const QAudioFormat &a, const QAudioFormat &b)
+
+    Returns \c true if audio format \a a is not equal to \a b, otherwise returns \c false.
 */
 
 /*!
@@ -136,7 +142,10 @@ QT_BEGIN_NAMESPACE
     \value BottomFrontLeft
     \value BottomFrontRight
 */
-
+/*!
+    \variable QAudioFormat::NChannelPositions
+    \internal
+*/
 
 /*!
     \enum QAudioFormat::ChannelConfig
@@ -146,15 +155,22 @@ QT_BEGIN_NAMESPACE
     and 7.1 surround configurations.
 
     \value ChannelConfigUnknown The channel configuration is not known.
-    \value ChannelConfigMono The audio has one Center channel
-    \value ChannelConfigStereo The audio has two channels, Left and Right
-    \value ChannelConfig2Dot1 The audio has three channels, Left, Right and LFE (low frequency effect)
-    \value ChannelConfig3Dot0 The audio has three channels, Left, Right and Center
-    \value ChannelConfig3Dot1 The audio has four channels, Left, Right, Center and LFE (low frequency effect)
-    \value ChannelConfigSurround5Dot0 The audio has five channels, Left, Right, Center, BackLeft, BackRight
-    \value ChannelConfigSurround5Dot1 The audio has 6 channels, Left, Right, Center, LFE, BackLeft and BackRight
-    \value ChannelConfigSurround7Dot0 The audio has 7 channels, Left, Right, Center, BackLeft, BackRight, SideLeft and SideRight
-    \value ChannelConfigSurround7Dot1 The audio has 8 channels, Left, Right, Center, LFE, BackLeft, BackRight, SideLeft and SideRight
+    \value ChannelConfigMono The audio has one Center channel.
+    \value ChannelConfigStereo The audio has two channels, Left and Right.
+    \value ChannelConfig2Dot1 The audio has three channels, Left, Right and
+           LFE (low frequency effect).
+    \value ChannelConfig3Dot0 The audio has three channels, Left, Right, and
+           Center.
+    \value ChannelConfig3Dot1 The audio has four channels, Left, Right, Center,
+           and LFE (low frequency effect).
+    \value ChannelConfigSurround5Dot0 The audio has five channels, Left, Right,
+           Center, BackLeft, and BackRight.
+    \value ChannelConfigSurround5Dot1 The audio has 6 channels, Left, Right,
+           Center, LFE, BackLeft, and BackRight.
+    \value ChannelConfigSurround7Dot0 The audio has 7 channels, Left, Right,
+           Center, BackLeft, BackRight, SideLeft, and SideRight.
+    \value ChannelConfigSurround7Dot1 The audio has 8 channels, Left, Right,
+           Center, LFE, BackLeft, BackRight, SideLeft, and SideRight.
 */
 
 /*!
@@ -194,7 +210,11 @@ int QAudioFormat::channelOffset(AudioChannelPosition channel) const noexcept
     config to ChannelConfigUnknown.
 */
 
+/*!
+    \fn template <typename... Args> QAudioFormat::ChannelConfig QAudioFormat::channelConfig(Args... channels)
 
+    Returns the current channel configuration for the given \a channels.
+*/
 /*!
     \fn QAudioFormat::ChannelConfig QAudioFormat::channelConfig() const noexcept
 
@@ -340,11 +360,15 @@ float QAudioFormat::normalizedSampleValue(const void *sample) const
 {
     switch (m_sampleFormat) {
     case UInt8:
-        return ((float)*reinterpret_cast<const quint8 *>(sample))/(float)std::numeric_limits<qint8>::max() - 1.;
+        return ((float)*reinterpret_cast<const quint8 *>(sample))
+                / (float)std::numeric_limits<qint8>::max()
+                - 1.;
     case Int16:
-        return ((float)*reinterpret_cast<const qint16 *>(sample))/(float)std::numeric_limits<qint16>::max();
+        return ((float)*reinterpret_cast<const qint16 *>(sample))
+                / (float)std::numeric_limits<qint16>::max();
     case Int32:
-        return ((float)*reinterpret_cast<const qint32 *>(sample))/(float)std::numeric_limits<qint32>::max();
+        return ((float)*reinterpret_cast<const qint32 *>(sample))
+                / (float)std::numeric_limits<qint32>::max();
     case Float:
         return *reinterpret_cast<const float *>(sample);
     case Unknown:
@@ -442,12 +466,10 @@ QDebug operator<<(QDebug dbg, QAudioFormat::SampleFormat type)
 
 QDebug operator<<(QDebug dbg, const QAudioFormat &f)
 {
-    dbg << "QAudioFormat(" << f.sampleRate() << "Hz, " << f.channelCount() << "Channels, " << f.sampleFormat() << "Format )";
+    dbg << "QAudioFormat(" << f.sampleRate() << "Hz, " << f.channelCount() << "Channels, "
+        << f.sampleFormat() << "Format )";
     return dbg;
 }
 #endif
 
-
-
 QT_END_NAMESPACE
-
diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index f8c088e97..c2477539b 100644
--- a/src/multimedia/audio/qaudioinput.cpp
+++ b/src/multimedia/audio/qaudioinput.cpp
@@ -1,5 +1,6 @@
 // Copyright (C) 2021 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR
+// GPL-3.0-only
 
 #include <qaudioinput.h>
 #include <qaudiodevice.h>
@@ -33,10 +34,10 @@
     }
     \endqml
 
-    You can use AudioInput together with a QtMultiMedia::CaptureSession to capture audio from an audio
-    input device.
+    You can use AudioInput together with a QtMultiMedia::CaptureSession to capture audio from an
+   audio input device.
 
-    \sa Camera AudioOutput
+    \sa Camera, AudioOutput
 */
 
 /*!
@@ -51,9 +52,9 @@
     to be used, muting the channel, and changing the channel's volume.
 */
 
-QAudioInput::QAudioInput(QObject *parent)
-    : QAudioInput(QMediaDevices::defaultAudioInput(), parent)
-{}
+QAudioInput::QAudioInput(QObject *parent) : QAudioInput(QMediaDevices::defaultAudioInput(), parent)
+{
+}
 
 QAudioInput::QAudioInput(const QAudioDevice &device, QObject *parent)
     : QObject(parent)
@@ -88,6 +89,11 @@ QAudioInput::~QAudioInput()
     which is what a user would normally expect from a volume control.
     \sa QAudio::convertVolume()
 */
+/*!
+    \property QAudioInput::volume
+
+    The property returns the volume of the audio input.
+*/
 float QAudioInput::volume() const
 {
     return d->volume;
diff --git a/src/multimedia/audio/qaudiooutput.cpp b/src/multimedia/audio/qaudiooutput.cpp
index 60cf0d476..0c87ce842 100644
--- a/src/multimedia/audio/qaudiooutput.cpp
+++ b/src/multimedia/audio/qaudiooutput.cpp
@@ -1,5 +1,6 @@
 // Copyright (C) 2021 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR
+// GPL-3.0-only
 
 #include <qaudiooutput.h>
 #include <qaudiodevice.h>
@@ -31,10 +32,11 @@
     }
     \endqml
 
-    You can use AudioOutput together with a QtMultiMedia::MediaPlayer to play audio content, or you can use it
-    in conjunction with a MultiMedia::CaptureSession to monitor the audio processed by the capture session.
+    You can use AudioOutput together with a QtMultiMedia::MediaPlayer to play audio content, or you
+   can use it in conjunction with a MultiMedia::CaptureSession to monitor the audio processed by the
+   capture session.
 
-    \sa VideoOutput AudioInput
+    \sa VideoOutput, AudioInput
 */
 
 /*!
@@ -52,7 +54,8 @@
 */
 QAudioOutput::QAudioOutput(QObject *parent)
     : QAudioOutput(QMediaDevices::defaultAudioOutput(), parent)
-{}
+{
+}
 
 QAudioOutput::QAudioOutput(const QAudioDevice &device, QObject *parent)
     : QObject(parent)
@@ -74,7 +77,6 @@ QAudioOutput::~QAudioOutput()
     delete d;
 }
 
-
 /*!
     \qmlproperty real QtMultimedia::AudioOutput::volume
 
@@ -205,5 +207,4 @@ void QAudioOutput::setDisconnectFunction(std::function<void()> disconnectFunctio
     d->disconnectFunction = std::move(disconnectFunction);
 }
 
-
 #include "moc_qaudiooutput.cpp"
diff --git a/src/multimedia/audio/qaudiosink.cpp b/src/multimedia/audio/qaudiosink.cpp
index ff9c217b8..20e1a83fc 100644
--- a/src/multimedia/audio/qaudiosink.cpp
+++ b/src/multimedia/audio/qaudiosink.cpp
@@ -94,6 +94,13 @@ QAudioSink::QAudioSink(const QAudioDevice &audioDevice, const QAudioFormat &form
 }
 
 /*!
+    \fn bool QAudioSink::isNull() const
+
+    Returns \c true is the QAudioSink instance is \c null, otherwise returns
+    \c false.
+*/
+
+/*!
     Destroys this audio output.
 
     This will release any system resources used and free any buffers.
diff --git a/src/multimedia/audio/qaudiosource.cpp b/src/multimedia/audio/qaudiosource.cpp
index 727a4f73b..3ed48449e 100644
--- a/src/multimedia/audio/qaudiosource.cpp
+++ b/src/multimedia/audio/qaudiosource.cpp
@@ -105,6 +105,12 @@ QAudioSource::QAudioSource(const QAudioDevice &audioDevice, const QAudioFormat &
 }
 
 /*!
+    \fn bool QAudioSource::isNull() const
+
+    Returns \c true if the audio source is \c null, otherwise returns \c false.
+*/
+
+/*!
     Destroy this audio input.
 */
 
diff --git a/src/multimedia/audio/qsoundeffect.cpp b/src/multimedia/audio/qsoundeffect.cpp
index b8e23c4d8..8127fb0b1 100644
--- a/src/multimedia/audio/qsoundeffect.cpp
+++ b/src/multimedia/audio/qsoundeffect.cpp
@@ -450,6 +450,11 @@ void QSoundEffect::setLoopCount(int loopCount)
     emit loopCountChanged();
 }
 
+/*!
+    \property QSoundEffect::audioDevice
+
+    Returns the QAudioDevice instance.
+*/
 QAudioDevice QSoundEffect::audioDevice()
 {
     return d->m_audioDevice;