Extend QSerialPortInfo docs

Provide a snippet that shows serial port enumeration.
This allows to get rid of two examples.

Task-number: QTBUG-110645
Pick-to: 6.5
Change-Id: I64649de331e116fc6e0f2b4c7d0d46e3198698e2
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

3 files changed, 61 insertions, 8 deletions

diff --git a/src/serialport/doc/qtserialport.qdocconf b/src/serialport/doc/qtserialport.qdocconf
index 270449f..a852fb3 100644
--- a/src/serialport/doc/qtserialport.qdocconf
+++ b/src/serialport/doc/qtserialport.qdocconf
@@ -27,12 +27,16 @@ qhp.QtSerialPort.subprojects.examples.sortPages = true
 
 headerdirs  += ..
 sourcedirs  += ..
-exampledirs += ../../../examples/serialport
+exampledirs += \
+    ../../../examples/serialport \
+    snippets
+
+excludedirs += snippets
 imagedirs   += images
 
 examplesinstallpath = serialport
 
-depends += qtcore qtdoc qtnetwork qmake
+depends += qtcore qtdoc qtnetwork qmake qtcmake
 
 navigation.landingpage = "Qt Serial Port"
 navigation.cppclassespage = "Qt Serial Port C++ Classes"
diff --git a/src/serialport/doc/snippets/doc_src_serialport.cpp b/src/serialport/doc/snippets/doc_src_serialport.cpp
new file mode 100644
index 0000000..11476c9
--- /dev/null
+++ b/src/serialport/doc/snippets/doc_src_serialport.cpp
@@ -0,0 +1,41 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+#include <QtCore/qcoreapplication.h>
+#include <QtCore/qdebug.h>
+
+#include <QtSerialPort/qserialportinfo.h>
+
+void enumeratePorts()
+{
+//! [enumerate_ports]
+    const auto serialPortInfos = QSerialPortInfo::availablePorts();
+    for (const QSerialPortInfo &portInfo : serialPortInfos) {
+        qDebug() << "\n"
+                 << "Port:" << portInfo.portName() << "\n"
+                 << "Location:" << portInfo.systemLocation() << "\n"
+                 << "Description:" << portInfo.description() << "\n"
+                 << "Manufacturer:" << portInfo.manufacturer() << "\n"
+                 << "Serial number:" << portInfo.serialNumber() << "\n"
+                 << "Vendor Identifier:"
+                 << (portInfo.hasVendorIdentifier()
+                     ? QByteArray::number(portInfo.vendorIdentifier(), 16)
+                     : QByteArray()) << "\n"
+                 << "Product Identifier:"
+                 << (portInfo.hasProductIdentifier()
+                     ? QByteArray::number(portInfo.productIdentifier(), 16)
+                     : QByteArray());
+    }
+//! [enumerate_ports]
+}
+
+int main(int argc, char **argv)
+{
+    QCoreApplication app(argc, argv);
+
+    enumeratePorts();
+
+    return app.exec();
+}
+
+#include "doc_src_serialport.moc"
diff --git a/src/serialport/qserialportinfo.cpp b/src/serialport/qserialportinfo.cpp
index 094fbda..be58f69 100644
--- a/src/serialport/qserialportinfo.cpp
+++ b/src/serialport/qserialportinfo.cpp
@@ -26,12 +26,20 @@ static_assert(sizeof(std::unique_ptr<QSerialPortInfoPrivate>)
     \inmodule QtSerialPort
     \since 5.1
 
-    Use the static functions to generate a list of QSerialPortInfo
-    objects. Each QSerialPortInfo object in the list represents a single
-    serial port and can be queried for the port name, system location,
-    description, and manufacturer. The QSerialPortInfo class can also be
-    used as an input parameter for the setPort() method of the QSerialPort
-    class.
+    Use the static \l availablePorts() function to generate a list of
+    QSerialPortInfo objects. Each QSerialPortInfo object in the list represents
+    a single serial port and can be queried for the \l {portName}{port name},
+    \l {systemLocation}{system location}, \l description, \l manufacturer, and
+    some other hardware parameters. The QSerialPortInfo class can also be
+    used as an input parameter for the \l {QSerialPort::}{setPort()} method of
+    the QSerialPort class.
+
+    \section1 Example Usage
+
+    The example code enumerates all available serial ports and prints their
+    parameters to console:
+
+    \snippet doc_src_serialport.cpp enumerate_ports
 
     \sa QSerialPort
 */