Move QMediaDevices example to manual tests and improve documentation

The Devices example is too simple to have as a full fledged example, and
can better be expressed through snippets. Therefore, this patch moves
the Devices example to manual tests, and improves the QMediaDevices doc
by adding some snippets.

Task-number: QTBUG-119117
Pick-to: 6.7 6.6 6.5
Change-Id: Id7c61e4f1b1047b73bae7e0619cf6238a30b8320
Reviewed-by: Artem Dyomin <artem.dyomin@qt.io>

7 files changed, 52 insertions, 5 deletions

diff --git a/examples/multimedia/CMakeLists.txt b/examples/multimedia/CMakeLists.txt
index fb5d62383..fc91cc40a 100644
--- a/examples/multimedia/CMakeLists.txt
+++ b/examples/multimedia/CMakeLists.txt
@@ -2,9 +2,6 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 qt_internal_add_example(audiodecoder)
-if(NOT ANDROID AND NOT IOS)
-    qt_internal_add_example(devices)
-endif()
 if(TARGET Qt::Widgets)
     if(NOT ANDROID AND NOT IOS)
         qt_internal_add_example(audiodevices)
diff --git a/examples/multimedia/multimedia.pro b/examples/multimedia/multimedia.pro
index 7267630b5..9adbd797e 100644
--- a/examples/multimedia/multimedia.pro
+++ b/examples/multimedia/multimedia.pro
@@ -2,8 +2,7 @@ TEMPLATE = subdirs
 QT_FOR_CONFIG += multimedia-private
 
 SUBDIRS += \
-    audiodecoder \
-    devices
+    audiodecoder
 
 # These examples all need widgets for now (using creator templates that use widgets)
 qtHaveModule(widgets) {
diff --git a/src/multimedia/doc/snippets/multimedia-snippets/devices.cpp b/src/multimedia/doc/snippets/multimedia-snippets/devices.cpp
new file mode 100644
index 000000000..652400364
--- /dev/null
+++ b/src/multimedia/doc/snippets/multimedia-snippets/devices.cpp
@@ -0,0 +1,38 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+#include <QAudioDevice>
+#include <QCameraDevice>
+#include <QMediaDevices>
+#include <QString>
+#include <QTextStream>
+
+int main(int argc, char *argv[])
+{
+    Q_UNUSED(argc);
+    Q_UNUSED(argv);
+
+    QTextStream out(stdout);
+
+    //! [Media Audio Input Device Enumeration]
+    const QList<QAudioDevice> audioDevices = QMediaDevices::audioInputs();
+    for (const QAudioDevice &device : audioDevices)
+    {
+        out << "ID: " << device.id() << Qt::endl;
+        out << "Description: " << device.description() << Qt::endl;
+        out << "Is default: " << (device.isDefault() ? "Yes" : "No") << Qt::endl;
+    }
+    //! [Media Audio Input Device Enumeration]
+
+    //! [Media Video Input Device Enumeration]
+    const QList<QCameraDevice> videoDevices = QMediaDevices::videoInputs();
+    for (const QCameraDevice &device : videoDevices)
+    {
+        out << "ID: " << device.id() << Qt::endl;
+        out << "Description: " << device.description() << Qt::endl;
+        out << "Is default: " << (device.isDefault() ? "Yes" : "No") << Qt::endl;
+    }
+    //! [Media Video Input Device Enumeration]
+
+    return 0;
+}
diff --git a/src/multimedia/qmediadevices.cpp b/src/multimedia/qmediadevices.cpp
index 3f37d85a8..fa6f8630e 100644
--- a/src/multimedia/qmediadevices.cpp
+++ b/src/multimedia/qmediadevices.cpp
@@ -30,6 +30,19 @@ QT_BEGIN_NAMESPACE
     from the system, it will update the corresponding device list and emit a signal
     notifying about the change.
 
+    The QMediaDevices::audioInputs and QMediaDevices::audioOutputs functions can be used
+    to enumerate all microphones and speakers/headsets on the system. This example first
+    gets a list of all connected microphones, and then prints their identifier, description,
+    and if it is the default device or not.
+
+    \snippet multimedia-snippets/devices.cpp Media Audio Input Device Enumeration
+
+    Similarly, the QMediaDevices::videoInputs will return a list of all connected cameras.
+    In this example we list all connected cameras and their identifier, description, and
+    if it is the default camera or not.
+
+    \snippet multimedia-snippets/devices.cpp Media Video Input Device Enumeration
+
     QMediaDevices monitors the system defaults for each device group. It will notify about
     any changes done through the system settings. For example, if the user selects a new
     default audio output in the system settings, QMediaDevices will update the default audio
diff --git a/examples/multimedia/devices/CMakeLists.txt b/tests/manual/devices/CMakeLists.txt
index d0856af45..d0856af45 100644
--- a/examples/multimedia/devices/CMakeLists.txt
+++ b/tests/manual/devices/CMakeLists.txt
diff --git a/examples/multimedia/devices/devices.pro b/tests/manual/devices/devices.pro
index bbc5ecea8..bbc5ecea8 100644
--- a/examples/multimedia/devices/devices.pro
+++ b/tests/manual/devices/devices.pro
diff --git a/examples/multimedia/devices/main.cpp b/tests/manual/devices/main.cpp
index 6c7f46a0b..6c7f46a0b 100644
--- a/examples/multimedia/devices/main.cpp
+++ b/tests/manual/devices/main.cpp