QML API and doc fixes

Export the enumerations in QCameraDevice and QAudioDevice, and
add missing QML and C++ documentation for those classes.

Change-Id: I7ad61bc007f5965c7d511225686d21154c196bd3
Reviewed-by: Piotr Srebrny <piotr.srebrny@qt.io>
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
(cherry picked from commit 18159127cfb548301a7e421cdb9d94faec511a8a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 196 insertions, 1 deletions

diff --git a/src/multimedia/audio/qaudiodevice.cpp b/src/multimedia/audio/qaudiodevice.cpp
index bc2bed906..9eebbbfe3 100644
--- a/src/multimedia/audio/qaudiodevice.cpp
+++ b/src/multimedia/audio/qaudiodevice.cpp
@@ -92,6 +92,34 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QAudioDevicePrivate);
 */
 
 /*!
+    \qmltype audioDevice
+    \inqmlmodule QtMultimedia
+    \since 6.2
+    \instantiates QAudioDevice
+    \brief Describes an audio device.
+    \ingroup multimedia_qml
+    \ingroup multimedia_audio_qml
+
+    The audioDevice value type describes the properties of an audio device that
+    is connected to the system.
+
+    The list of audio input or output devices can be queried from the \l{MediaDevices}
+    type. To select a certain audio device for input or output set it as the device
+    on \l{AudioInput} or \l{AudioOutput}.
+
+    \qml
+    MediaPlayer {
+        audioOutput: AudioOutput {
+            device: mediaDevices.defaultAudioOutput
+        }
+    }
+    MediaDevices {
+        id: mediaDevices
+    }
+    \endqml
+*/
+
+/*!
     Constructs a null QAudioDevice object.
 */
 QAudioDevice::QAudioDevice() = default;
@@ -156,6 +184,16 @@ bool QAudioDevice::isNull() const
 }
 
 /*!
+    \qmlmethod string QtMultimedia::audioDevice::id
+
+    Returns an identifier for the audio device.
+
+    Device names vary depending on the platform/audio plugin being used.
+
+    They are a unique identifier for the audio device.
+*/
+
+/*!
     Returns an identifier for the audio device.
 
     Device names vary depending on the platform/audio plugin being used.
@@ -168,6 +206,14 @@ QByteArray QAudioDevice::id() const
 }
 
 /*!
+    \qmlmethod string QtMultimedia::audioDevice::description
+
+    Returns a human readable name of the audio device.
+
+    Use this string to present the device to the user.
+*/
+
+/*!
     Returns a human readable name of the audio device.
 
     Use this string to present the device to the user.
@@ -178,7 +224,13 @@ QString QAudioDevice::description() const
 }
 
 /*!
-    Returns true if this is the default audio device for it's mode.
+    \qmlmethod bool QtMultimedia::audioDevice::isDefault
+
+    Returns true if this is the default audio device.
+*/
+
+/*!
+    Returns true if this is the default audio device.
 */
 bool QAudioDevice::isDefault() const
 {
@@ -272,6 +324,39 @@ QAudioDevice::QAudioDevice(QAudioDevicePrivate *p)
 {}
 
 /*!
+    \enum QAudioDevice::mode
+
+    Describes the mode of a QAudioDevice
+
+    \value Null
+         A null device.
+    \value Input
+         An input device.
+    \value Output
+        An output device.
+*/
+
+/*!
+    \qmlmethod enumeration QtMultimedia::audioDevice::mode
+
+    Tells whether this device is an input or output device.
+
+    The returned value can be one of the following:
+
+    \table
+    \header
+        \li Property value
+        \li Description
+    \row \li AudioDevice.Null
+        \li A null device.
+    \row \li AudioDevice.Input
+        \li An input device.
+    \row \li AudioDevice.Output
+        \li An output device.
+    \endtable
+*/
+
+/*!
     returns whether this device is an input or output device.
 */
 QAudioDevice::Mode QAudioDevice::mode() const
diff --git a/src/multimedia/camera/qcameradevice.cpp b/src/multimedia/camera/qcameradevice.cpp
index dec01524b..47b5d1b95 100644
--- a/src/multimedia/camera/qcameradevice.cpp
+++ b/src/multimedia/camera/qcameradevice.cpp
@@ -122,6 +122,34 @@ bool QCameraFormat::operator==(const QCameraFormat &other) const
 */
 
 /*!
+    \qmltype cameraDevice
+    \inqmlmodule QtMultimedia
+    \since 6.2
+    \instantiates QCameraDevice
+    \brief Describes a camera device.
+    \ingroup multimedia_qml
+    \ingroup multimedia_video_qml
+
+    The cameraDevice value type describes the properties of a camera device that
+    is connected to the system.
+
+    The list of camera devices can be queried from the \l{MediaDevices}
+    type. To select a certain camera device set it as the device
+    on \l{Camera}.
+
+    \qml
+    CaptureSession {
+        camera: Camera {
+            device: mediaDevices.defaultVideoInput
+        }
+    }
+    MediaDevices {
+        id: mediaDevices
+    }
+    \endqml
+*/
+
+/*!
   Constructs a null camera device
 */
 QCameraDevice::QCameraDevice() = default;
@@ -161,6 +189,14 @@ bool QCameraDevice::isNull() const
 }
 
 /*!
+    \qmlmethod string QtMultimedia::cameraDevice::id
+
+    Returns the device id of the camera
+
+    This is a unique ID to identify the camera and may not be human-readable.
+*/
+
+/*!
     Returns the device id of the camera
 
     This is a unique ID to identify the camera and may not be human-readable.
@@ -170,13 +206,32 @@ QByteArray QCameraDevice::id() const
     return d ? d->id : QByteArray();
 }
 
+/*!
+    \qmlmethod bool QtMultimedia::cameraDevice::isDefault
+
+    Returns true if this is the default camera device.
+*/
+
+/*!
+    Returns true if this is the default camera device.
+*/
 bool QCameraDevice::isDefault() const
 {
     return d ? d->isDefault : false;
 }
 
 /*!
+    \qmlmethod string QtMultimedia::cameraDevice::description
+
+    Returns a human readable name of the camera.
+
+    Use this string to present the device to the user.
+*/
+
+/*!
     Returns the human-readable description of the camera.
+
+    Use this string to present the device to the user.
 */
 QString QCameraDevice::description() const
 {
@@ -184,6 +239,41 @@ QString QCameraDevice::description() const
 }
 
 /*!
+    \enum QCameraDevice::Position
+
+    Describes the physical position of the camera on the hardware system.
+
+    \value CameraDevice.UnspecifiedPosition
+        The physical positition of the camera is unspecified.
+    \value CameraDevice.FrontFace
+        The camera is on the front of the hardware, facing towards the user.
+    \value CameraDevice.BackFace
+        The camera is on the back of the hardware, facing away from the user.
+    \endtable
+*/
+
+
+/*!
+    \qmlmethod enumeration QtMultimedia::cameraDevice::position
+
+    Returns the physical position of the camera on the hardware system.
+
+    The returned value can be one of the following:
+
+    \table
+    \header
+        \li Property value
+        \li Description
+    \row \li CameraDevice.UnspecifiedPosition
+        \li The physical positition of the camera is unspecified.
+    \row \li CameraDevice.FrontFace
+        \li The camera is on the front of the hardware, facing towards the user.
+    \row \li CameraDevice.BackFace
+        \li The camera is on the back of the hardware, facing away from the user.
+    \endtable
+*/
+
+/*!
     Returns the physical position of the camera on the hardware system.
 */
 QCameraDevice::Position QCameraDevice::position() const
@@ -191,6 +281,12 @@ QCameraDevice::Position QCameraDevice::position() const
     return d ? d->position : QCameraDevice::UnspecifiedPosition;
 }
 
+/*!
+    Returns a list of resolutions that the camera can use to
+    capture still images.
+
+    \sa QCameraImageCapture
+ */
 QList<QSize> QCameraDevice::photoResolutions() const
 {
     return d->photoResolutions;
diff --git a/src/multimediaquick/qtmultimediaquicktypes_p.h b/src/multimediaquick/qtmultimediaquicktypes_p.h
index e3d6bed78..26765683b 100644
--- a/src/multimediaquick/qtmultimediaquicktypes_p.h
+++ b/src/multimediaquick/qtmultimediaquicktypes_p.h
@@ -141,6 +141,13 @@ struct QAudioDeviceForeign
     QML_NAMED_ELEMENT(audioDevice)
 };
 
+namespace QAudioDeviceNamespaceForeign
+{
+    Q_NAMESPACE
+    QML_FOREIGN_NAMESPACE(QAudioDevice)
+    QML_NAMED_ELEMENT(AudioDevice)
+};
+
 struct QCameraDeviceForeign
 {
     Q_GADGET
@@ -148,6 +155,13 @@ struct QCameraDeviceForeign
     QML_NAMED_ELEMENT(cameraDevice)
 };
 
+namespace QCameraDeviceNamespaceForeign
+{
+    Q_NAMESPACE
+    QML_FOREIGN_NAMESPACE(QCameraDevice)
+    QML_NAMED_ELEMENT(CameraDevice)
+};
+
 struct QMediaFormatForeign
 {
     Q_GADGET