Modbus Client: update example description

Extend the example description so that it actually highlights the main
features shown in the example.

Also update the example to match the guidelines:
* Do not use Example in the name
* Update screenshot
* add Connectivity category

Task-number: QTBUG-110890
Change-Id: I2296371e93b7427db960081ac10efac8deae15af
Reviewed-by: André Hartmann <aha_1980@gmx.de>
(cherry picked from commit 20d4cba63221cb144537518e492187ff82a590fa)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

6 files changed, 94 insertions, 10 deletions

diff --git a/examples/serialbus/modbus/client/doc/images/modbusclient.png b/examples/serialbus/modbus/client/doc/images/modbusclient.png
index b2d771c..8d33723 100644
--- a/examples/serialbus/modbus/client/doc/images/modbusclient.png
+++ b/examples/serialbus/modbus/client/doc/images/modbusclient.png
diff --git a/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc b/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc
index dd209c3..85c1d31 100644
--- a/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc
+++ b/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc
@@ -1,19 +1,90 @@
-// Copyright (C) 2017 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*! \example modbus/client
-    \title Modbus Client example
+    \title Modbus Client
+    \ingroup qtserialbus-examples
+    \meta category Connectivity
 
     \brief The example implements a Modbus client application.
 
     The example acts as Modbus client sending Modbus request via serial line
-    and TCP respectively. The shown dialog allows the definition of standard
-    requests and displays incoming responses.
+    or TCP. The shown dialog allows the definition of standard requests and
+    displays incoming responses.
+
+    The example must be used in conjunction with the \l {Modbus server example}
+    or another Modbus device which is either connected via TCP or Serial Port.
+
+    Key classes used in this example:
+
+    \list
+        \li \l QModbusClient
+        \li \l QModbusDataUnit
+        \li \l QModbusReply
+    \endlist
 
     \image ../images/modbusclient.png
 
-    \include examples-run.qdocinc
+    \section1 Creating a QModbusClient
 
-    The example must be used in conjunction with the \l {Modbus server example}
-    or another Modbus device which is either connected via TCP or Serial Port.
+    An instance of \l QModbusClient is required to perform any communication.
+    Depending on the specified connection type, the example can instantiate
+    a \l QModbusRtuSerialClient (for serial communication), or a
+    \l QModbusTcpClient (for TCP-based communication).
+
+    \snippet modbus/client/mainwindow.cpp create_client_0
+
+    Once the client is created, use the
+    \l {QModbusClient::}{setConnectionParameter()} method to specify the
+    connection parameters. The parameters vary depending on the communication
+    type:
+
+    \snippet modbus/client/mainwindow.cpp create_client_1
+
+    After the client is created and all the parameters are specified, use
+    \l {QModbusClient::connectDevice()} to connect to Modbus network.
+
+    \section1 Reading Data
+
+    To read data from Modbus server, the client needs to specify a
+    server address and the parameters of objects that it wants to read:
+    \list
+        \li \l {QModbusDataUnit::}{RegisterType}
+        \li \l {QModbusDataUnit::startAddress}{start address}
+        \li \l {QModbusDataUnit::valueCount}{number of entries to read}
+    \endlist
+
+    The object parameters are represented by the \l QModbusDataUnit class:
+
+    \snippet modbus/client/mainwindow.cpp read_data_0
+
+    Once the parameters are collected, the
+    \l {QModbusClient::}{sendReadRequest()} method is used to send the actual
+    request. The method returns a \l QModbusReply which should be processed
+    in an asynchronous way, so the \l QModbusReply::finished() signal is used
+    to check when the reply is ready.
+
+    \snippet modbus/client/mainwindow.cpp read_data_1
+
+    Once the \l QModbusReply::finished() signal is received, the reply object
+    can be used to get the data or to check for read errors:
+
+    \snippet modbus/client/mainwindow.cpp read_data_2
+
+    \section1 Writing Data
+
+    To write the data to the Modbus server, the client needs to specify the
+    server address, and the parameters of objects that it wants to write.
+    As with reading the data, the \l QModbusDataUnit class is used to represent
+    the information about the data to be written. This time the data also
+    includes the desired \l {QModbusDataUnit::}{values}.
+    The \l {QModbusClient::}{sendWriteRequest()} method is used to write the
+    desired data:
+
+    \snippet modbus/client/mainwindow.cpp write_data_0
+
+    Like with reading the data, the returned \l QModbusReply object is used
+    to check for write errors.
+
+    \include examples-run.qdocinc
 */
diff --git a/examples/serialbus/modbus/client/mainwindow.cpp b/examples/serialbus/modbus/client/mainwindow.cpp
index 81ac626..308e8d1 100644
--- a/examples/serialbus/modbus/client/mainwindow.cpp
+++ b/examples/serialbus/modbus/client/mainwindow.cpp
@@ -130,6 +130,7 @@ void MainWindow::onConnectTypeChanged(int index)
         modbusDevice = nullptr;
     }
 
+//! [create_client_0]
     auto type = static_cast<ModbusConnection>(index);
     if (type == Serial) {
 #if QT_CONFIG(modbus_serialport)
@@ -148,6 +149,7 @@ void MainWindow::onConnectTypeChanged(int index)
         if (currentUrl.port() <= 0)
             ui->portEdit->setText(QLatin1String("127.0.0.1:50200"));
     }
+//! [create_client_0]
 
     connect(modbusDevice, &QModbusClient::errorOccurred, [this](QModbusDevice::Error) {
         statusBar()->showMessage(modbusDevice->errorString(), 5000);
@@ -169,6 +171,7 @@ void MainWindow::onConnectButtonClicked()
 
     statusBar()->clearMessage();
     if (modbusDevice->state() != QModbusDevice::ConnectedState) {
+//! [create_client_1]
         const auto settings = m_settingsDialog->settings();
         if (static_cast<ModbusConnection>(ui->connectType->currentIndex()) == Serial) {
             modbusDevice->setConnectionParameter(QModbusDevice::SerialPortNameParameter,
@@ -190,6 +193,7 @@ void MainWindow::onConnectButtonClicked()
         }
         modbusDevice->setTimeout(settings.responseTime);
         modbusDevice->setNumberOfRetries(settings.numberOfRetries);
+//! [create_client_1]
         if (!modbusDevice->connectDevice()) {
             statusBar()->showMessage(tr("Connect failed: %1").arg(modbusDevice->errorString()), 5000);
         } else {
@@ -226,6 +230,7 @@ void MainWindow::onReadButtonClicked()
     ui->readValue->clear();
     statusBar()->clearMessage();
 
+//! [read_data_1]
     if (auto *reply = modbusDevice->sendReadRequest(readRequest(), ui->serverEdit->value())) {
         if (!reply->isFinished())
             connect(reply, &QModbusReply::finished, this, &MainWindow::onReadReady);
@@ -234,8 +239,10 @@ void MainWindow::onReadButtonClicked()
     } else {
         statusBar()->showMessage(tr("Read error: %1").arg(modbusDevice->errorString()), 5000);
     }
+//! [read_data_1]
 }
 
+//! [read_data_2]
 void MainWindow::onReadReady()
 {
     auto reply = qobject_cast<QModbusReply *>(sender());
@@ -262,6 +269,7 @@ void MainWindow::onReadReady()
 
     reply->deleteLater();
 }
+//! [read_data_2]
 
 void MainWindow::onWriteButtonClicked()
 {
@@ -269,6 +277,7 @@ void MainWindow::onWriteButtonClicked()
         return;
     statusBar()->clearMessage();
 
+//! [write_data_0]
     QModbusDataUnit writeUnit = writeRequest();
     QModbusDataUnit::RegisterType table = writeUnit.registerType();
     for (qsizetype i = 0, total = writeUnit.valueCount(); i < total; ++i) {
@@ -300,6 +309,7 @@ void MainWindow::onWriteButtonClicked()
     } else {
         statusBar()->showMessage(tr("Write error: %1").arg(modbusDevice->errorString()), 5000);
     }
+//! [write_data_0]
 }
 
 void MainWindow::onReadWriteButtonClicked()
@@ -344,6 +354,7 @@ void MainWindow::onWriteTableChanged(int index)
     ui->writeGroupBox->setEnabled(coilsOrHolding);
 }
 
+//! [read_data_0]
 QModbusDataUnit MainWindow::readRequest() const
 {
     const auto table = ui->writeTable->currentData().value<QModbusDataUnit::RegisterType>();
@@ -356,6 +367,7 @@ QModbusDataUnit MainWindow::readRequest() const
                                    quint16(10 - startAddress));
     return QModbusDataUnit(table, startAddress, numberOfEntries);
 }
+//! [read_data_0]
 
 QModbusDataUnit MainWindow::writeRequest() const
 {
diff --git a/examples/serialbus/modbus/client/mainwindow.ui b/examples/serialbus/modbus/client/mainwindow.ui
index 4c4eb4e..84aa33f 100644
--- a/examples/serialbus/modbus/client/mainwindow.ui
+++ b/examples/serialbus/modbus/client/mainwindow.ui
@@ -17,7 +17,7 @@
    </size>
   </property>
   <property name="windowTitle">
-   <string>Modbus Client Example</string>
+   <string>Modbus Client</string>
   </property>
   <widget class="QWidget" name="centralWidget">
    <layout class="QVBoxLayout" name="verticalLayout">
diff --git a/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc b/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc
index 674d789..ec27852 100644
--- a/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc
+++ b/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc
@@ -14,7 +14,8 @@
 
     \include examples-run.qdocinc
 
-    This example must be used in conjunction with the \l {Modbus Client example}.
+    This example must be used in conjunction with the
+    \l {modbus/client}{Modbus Client example}.
     This example should be started and put into the listen state before the
     Modbus client example is started. Subsequent interactions between the two
     examples use the Modbus protocol.
diff --git a/src/serialbus/doc/src/qtserialbus-index.qdoc b/src/serialbus/doc/src/qtserialbus-index.qdoc
index fd4c1cf..f4af1c2 100644
--- a/src/serialbus/doc/src/qtserialbus-index.qdoc
+++ b/src/serialbus/doc/src/qtserialbus-index.qdoc
@@ -75,7 +75,7 @@
 
     \list
          \li \l {can}{CAN Bus Manager example}
-         \li \l {Modbus Client example}
+         \li \l {modbus/client}{Modbus Client example}
          \li \l {Modbus Server example}
          \li \l {Modbus Custom command example}
     \endlist