Fix a number of doc errors and warnings.

* Document a few missing classes/functions/methods
* Fix a number of QML snippets that wouldn't work as standalone snippets
* Add files to .pro so they show up in Creator..

Still the mysterious lack of controls dir documentation persists :/

Change-Id: I57162371a4d966e4db5bdb1b71d1baf9c0ca57c3
Reviewed-by: Jonas Rabbe <jonas.rabbe@nokia.com>

3 files changed, 170 insertions, 16 deletions

diff --git a/src/multimedia/audio/qaudio.cpp b/src/multimedia/audio/qaudio.cpp
index f89783f46..4a516a0ac 100644
--- a/src/multimedia/audio/qaudio.cpp
+++ b/src/multimedia/audio/qaudio.cpp
@@ -62,7 +62,7 @@ public:
 
 }
 
-/*
+/*!
     \namespace QAudio
     \brief The QAudio namespace contains enums used by the audio classes.
     \inmodule QtMultimedia
@@ -70,7 +70,7 @@ public:
     \ingroup multimedia_audio
 */
 
-/*
+/*!
     \enum QAudio::Error
 
     \value NoError         No errors have occurred
@@ -80,7 +80,7 @@ public:
     \value FatalError      A non-recoverable error has occurred, the audio device is not usable at this time.
 */
 
-/*
+/*!
     \enum QAudio::State
 
     \value ActiveState     Audio data is being processed, this state is set after start() is called
@@ -92,7 +92,7 @@ public:
                            is set after start() is called and while no audio data is available to be processed.
 */
 
-/*
+/*!
     \enum QAudio::Mode
 
     \value AudioOutput   audio output device
diff --git a/src/multimedia/audio/qaudiobuffer.cpp b/src/multimedia/audio/qaudiobuffer.cpp
index 7161e44d4..bde04501f 100644
--- a/src/multimedia/audio/qaudiobuffer.cpp
+++ b/src/multimedia/audio/qaudiobuffer.cpp
@@ -371,7 +371,18 @@ qint64 QAudioBuffer::startTime() const
 
     This method is preferred over the const version of \l data() to
     prevent unnecessary copying.
- */
+
+    There is also a templatized version of this constData() function that
+    allows you to retrieve a specific type of read-only pointer to
+    the data.  Note that there is no checking done on the format of
+    the audio buffer - this is simply a convenience function.
+
+    \code
+    // With a 16bit sample buffer:
+    const quint16 *data = buffer->constData<quint16>();
+    \endcode
+
+*/
 const void* QAudioBuffer::constData() const
 {
     if (!isValid())
@@ -384,7 +395,17 @@ const void* QAudioBuffer::constData() const
 
     You should use the \l constData() function rather than this
     to prevent accidental deep copying.
- */
+
+    There is also a templatized version of this data() function that
+    allows you to retrieve a specific type of read-only pointer to
+    the data.  Note that there is no checking done on the format of
+    the audio buffer - this is simply a convenience function.
+
+    \code
+    // With a 16bit sample const buffer:
+    const quint16 *data = buffer->data<quint16>();
+    \endcode
+*/
 const void* QAudioBuffer::data() const
 {
     if (!isValid())
@@ -392,6 +413,12 @@ const void* QAudioBuffer::data() const
     return d->mProvider->constData();
 }
 
+
+/*
+    Template data/constData functions caused override problems with qdoc,
+    so moved their docs into the non template versions.
+*/
+
 /*!
     Returns a pointer to this buffer's data.  You can modify the
     data through the returned pointer.
@@ -407,7 +434,17 @@ const void* QAudioBuffer::data() const
     change both buffer instances.  Calling \l data() on either instance
     will again cause a deep copy to be made, which may invalidate
     the pointers returned from this function previously.
- */
+
+    There is also a templatized version of data() allows you to retrieve
+    a specific type of pointer to the data.  Note that there is no
+    checking done on the format of the audio buffer - this is
+    simply a convenience function.
+
+    \code
+    // With a 16bit sample buffer:
+    quint16 *data = buffer->data<quint16>(); // May cause deep copy
+    \endcode
+*/
 void *QAudioBuffer::data()
 {
     if (!isValid())
@@ -447,4 +484,119 @@ void *QAudioBuffer::data()
     return 0;
 }
 
+// Template helper classes worth documenting
+
+/*!
+    \class QAudioBuffer::StereoSampleDefault
+    \internal
+
+    Just a trait class for the default value.
+*/
+
+/*!
+    \class QAudioBuffer::StereoSample
+    \brief The StereoSample class provides a simple wrapper for a stereo audio sample.
+    \inmodule QtMultimedia
+    \ingroup multimedia
+    \ingroup multimedia_audio
+
+    This templatized structure lets you treat a block of individual samples as an
+    interleaved stereo stream.  This is most useful when used with the templatized
+    \l {QAudioBuffer::data()}{data()} functions of QAudioBuffer.  Generally the data
+    is accessed as a pointer, so no copying should occur.
+
+    There are some predefined instantiations of this template for working with common
+    stereo sample depths in a convenient way.
+
+    This structure has \e left and \e right members for accessing individual channel data.
+
+    For example:
+    \code
+    // Assuming 'buffer' is an unsigned 16 bit stereo buffer..
+    QAudioBuffer::S16U *sample = buffer->data<QAudioBuffer::S16U>();
+    for (int i=0; i < buffer->sampleCount() / 2; i++) {
+        qSwap(sample[i].left, sample[i].right);
+    }
+    \endcode
+
+    \sa QAudioBuffer::S8U, QAudioBuffer::S8S, QAudioBuffer::S16S, QAudioBuffer::S16U, QAudioBuffer::S32F
+*/
+
+/*!
+    \fn QAudioBuffer::StereoSample::StereoSample()
+
+    Constructs a new sample with the "silent" value for this
+    sample format (0 for signed formats and floats, 0x8* for unsigned formats).
+*/
+
+/*!
+    \fn QAudioBuffer::StereoSample::StereoSample(T leftSample, T rightSample)
+
+    Constructs a new sample with the supplied \a leftSample and \a rightSample values.
+*/
+
+/*!
+    \fn QAudioBuffer::StereoSample::operator=(const StereoSample &other)
+
+    Assigns \a other to this sample.
+ */
+
+
+/*!
+    \fn QAudioBuffer::StereoSample::average() const
+
+    Returns the arithmetic average of the left and right samples.
+ */
+
+/*! \fn QAudioBuffer::StereoSample::clear()
+
+    Sets the values of this sample to the "silent" value.
+*/
+
+/*!
+    \variable QAudioBuffer::StereoSample::left
+    \brief the left sample
+*/
+
+/*!
+    \variable QAudioBuffer::StereoSample::right
+    \brief the right sample
+*/
+
+/*!
+    \typedef QAudioBuffer::S8U
+    \relates QAudioBuffer::StereoSample
+
+    This is a predefined specialization for an unsigned stereo 8 bit sample.  Each
+    channel is an \e {unsigned char}.
+*/
+/*!
+    \typedef QAudioBuffer::S8S
+    \relates QAudioBuffer::StereoSample
+
+    This is a predefined specialization for a signed stereo 8 bit sample.  Each
+    channel is a \e {signed char}.
+*/
+/*!
+    \typedef QAudioBuffer::S16U
+    \relates QAudioBuffer::StereoSample
+
+    This is a predefined specialization for an unsigned stereo 16 bit sample.  Each
+    channel is an \e {unsigned short}.
+*/
+/*!
+    \typedef QAudioBuffer::S16S
+    \relates QAudioBuffer::StereoSample
+
+    This is a predefined specialization for a signed stereo 16 bit sample.  Each
+    channel is a \e {signed short}.
+*/
+/*!
+    \typedef QAudioBuffer::S32F
+    \relates QAudioBuffer::StereoSample
+
+    This is a predefined specialization for an 32 bit float sample.  Each
+    channel is a \e float.
+*/
+
 QT_END_NAMESPACE
diff --git a/src/multimedia/audio/qaudiodecoder_p.cpp b/src/multimedia/audio/qaudiodecoder_p.cpp
index 8776215ca..b0d57ee8f 100644
--- a/src/multimedia/audio/qaudiodecoder_p.cpp
+++ b/src/multimedia/audio/qaudiodecoder_p.cpp
@@ -69,7 +69,7 @@ QT_BEGIN_NAMESPACE
     directly to audio hardware, and playlists and network and streaming
     based media is not supported.
 
-    \sa QAudioBuffer, QAudioDecoder
+    \sa QAudioBuffer
 */
 
 namespace
@@ -130,7 +130,7 @@ void QAudioDecoderPrivate::_q_error(int error, const QString &errorString)
 
 /*!
     Construct an QAudioDecoder instance
-    parented to \a parent and with \a flags.
+    parented to \a parent.
 */
 QAudioDecoder::QAudioDecoder(QObject *parent)
     : QMediaObject(*new QAudioDecoderPrivate,
@@ -204,7 +204,7 @@ QString QAudioDecoder::errorString() const
     Alternatively, if you wish to block until enough data has been decoded,
     you can call read() at any time to block until a buffer is ready.
 
-    \sa read(), bufferSize()
+    \sa read()
 */
 void QAudioDecoder::start()
 {
@@ -267,7 +267,7 @@ void QAudioDecoder::setSourceFilename(const QString &fileName)
 
 /*!
     Returns the current source QIODevice, if one was set.
-    If \l setSourceFilename was called, this will be 0.
+    If \l setSourceFilename() was called, this will be 0.
 */
 QIODevice *QAudioDecoder::sourceDevice() const
 {
@@ -299,7 +299,7 @@ void QAudioDecoder::setSourceDevice(QIODevice *device)
 
     Any buffers returned should have this format.
 
-    \sa setAudioFormat, audioFormatChanged
+    \sa setAudioFormat(), formatChanged()
 */
 QAudioFormat QAudioDecoder::audioFormat() const
 {
@@ -366,6 +366,8 @@ QtMultimedia::SupportEstimate QAudioDecoder::hasSupport(const QString &mimeType,
 }
 
 /*!
+    \fn QAudioDecoder::bufferAvailable() const
+
     Returns true if a buffer is available to be read,
     and false otherwise.  If there is no buffer available, calling
     the \l read() function may block until a buffer is available or
@@ -471,7 +473,7 @@ QAudioBuffer QAudioDecoder::read() const
 
     Signals that the current audio format of the decoder has changed to \a format.
 
-    \sa audioFormat(), setAudioFormat
+    \sa audioFormat(), setAudioFormat()
 */
 
 /*!
@@ -498,7 +500,7 @@ QAudioBuffer QAudioDecoder::read() const
     Signals that the decoding has finished successfully.
     If decoding fails, error signal is emitted instead.
 
-    \sa start(), stop(), error
+    \sa start(), stop(), error()
 */
 
 /*!
@@ -506,7 +508,7 @@ QAudioBuffer QAudioDecoder::read() const
 
     Signals that the current \a position of the decoder has changed.
 
-    \sa durationChanged
+    \sa durationChanged()
 */
 
 /*!
@@ -514,7 +516,7 @@ QAudioBuffer QAudioDecoder::read() const
 
     Signals that the estimated \a duration of the decoded data has changed.
 
-    \sa positionChanged
+    \sa positionChanged()
 */