From a5098ab75c84d4c612f312b28d387203cf771ec3 Mon Sep 17 00:00:00 2001
From: Ivan Solovev <ivan.solovev@qt.io>
Date: Fri, 27 Jan 2023 16:36:36 +0100
Subject: Extend QSerialPortInfo docs

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

Task-number: QTBUG-110645
Change-Id: I64649de331e116fc6e0f2b4c7d0d46e3198698e2
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
(cherry picked from commit 63e54a5993a5e4df798cfd2ad4f44c4259098826)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 src/serialport/doc/qtserialport.qdocconf           |  8 +++--
 src/serialport/doc/snippets/doc_src_serialport.cpp | 41 ++++++++++++++++++++++
 src/serialport/qserialportinfo.cpp                 | 20 +++++++----
 3 files changed, 61 insertions(+), 8 deletions(-)
 create mode 100644 src/serialport/doc/snippets/doc_src_serialport.cpp

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
 */
-- 
cgit v1.2.1