Modbus Server: 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: I4eb7603630a9b69fff4cf921b5adff6ea4c125cf
Reviewed-by: André Hartmann <aha_1980@gmx.de>
(cherry picked from commit e448b2b4d402c7ef4c8b06d16a8307e5219b115a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

6 files changed, 79 insertions, 10 deletions

diff --git a/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc b/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc
index 85c1d31..e648f7a 100644
--- a/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc
+++ b/examples/serialbus/modbus/client/doc/src/modbusclient.qdoc
@@ -12,8 +12,9 @@
     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.
+    The example must be used in conjunction with the
+    \l {modbus/server}{Modbus Server example} or another Modbus device which is
+    either connected via TCP or Serial Port.
 
     Key classes used in this example:
 
diff --git a/examples/serialbus/modbus/server/doc/images/modbusserver.png b/examples/serialbus/modbus/server/doc/images/modbusserver.png
index 1506382..2bd8cea 100644
--- a/examples/serialbus/modbus/server/doc/images/modbusserver.png
+++ b/examples/serialbus/modbus/server/doc/images/modbusserver.png
diff --git a/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc b/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc
index ec27852..102b565 100644
--- a/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc
+++ b/examples/serialbus/modbus/server/doc/src/modbusserver.qdoc
@@ -1,8 +1,10 @@
-// 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/server
-    \title Modbus Server example
+    \title Modbus Server
+    \ingroup qtserialbus-examples
+    \meta category Connectivity
 
     \brief The example implements a Modbus server application.
 
@@ -10,13 +12,67 @@
     adjusts its internal states based on the request and responds with the
     appropriate reply.
 
-    \image ../images/modbusserver.png
-
-    \include examples-run.qdocinc
-
     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.
+
+    Key classes used in this example:
+
+    \list
+        \li \l QModbusServer
+        \li \l QModbusDataUnit
+    \endlist
+
+    \image ../images/modbusserver.png
+
+    \section1 Creating a QModbusServer
+
+    An instance of \l QModbusServer is required to perform any communication.
+    Depending on the specified connection type, the example can instantiate a
+    \l QModbusRtuSerialServer (for serial communication) or a
+    \l QModbusTcpServer (for TCP-based communication).
+
+    \snippet modbus/server/mainwindow.cpp create_server_0
+
+    Once the server is created, the register map is set using
+    \l QModbusServer::setMap() method. This register map is used by client
+    applications to read and write server data.
+
+    \snippet modbus/server/mainwindow.cpp create_server_1
+
+    After that the communication parameters and the server address are
+    specified. The communication parameters depend on the communication type:
+
+    \snippet modbus/server/mainwindow.cpp create_server_2
+
+    After the server is created and all the parameters are specified, use
+    \l QModbusServer::connectDevice() to connect to Modbus network.
+
+    \section1 Changing Local Values
+
+    The example allows to change values of all supported
+    \l {QModbusDataUnit::RegisterType}{register types} by using the provided
+    combo boxes or line edits. Once the value is updated in the UI, the
+    \l QModbusServer::setData() method is used to update the actual value on
+    the server:
+
+    \snippet modbus/server/mainwindow.cpp update_data_locally
+
+    \section1 Handling Remote Writes
+
+    The Modbus clients are capable of updating \l {QModbusDataUnit::}{Coils}
+    and \l {QModbusDataUnit::}{HoldingRegisters} by sending write requests.
+    Once the value is updated on the server side using such request, a
+    \l QModbusServer::dataWritten() signal is emitted.
+
+    \snippet modbus/server/mainwindow.cpp connect_data_written
+
+    The Modbus server example connects to this signal, extracts the updated
+    values and updates the UI accordingly:
+
+    \snippet modbus/server/mainwindow.cpp update_data_from_remote
+
+    \include examples-run.qdocinc
 */
diff --git a/examples/serialbus/modbus/server/mainwindow.cpp b/examples/serialbus/modbus/server/mainwindow.cpp
index 965c5aa..73b5301 100644
--- a/examples/serialbus/modbus/server/mainwindow.cpp
+++ b/examples/serialbus/modbus/server/mainwindow.cpp
@@ -82,6 +82,7 @@ void MainWindow::onCurrentConnectTypeChanged(int index)
         modbusDevice = nullptr;
     }
 
+//! [create_server_0]
     auto type = static_cast<ModbusConnection>(index);
     if (type == Serial) {
 #if QT_CONFIG(modbus_serialport)
@@ -100,12 +101,14 @@ void MainWindow::onCurrentConnectTypeChanged(int index)
         if (currentUrl.port() <= 0)
             ui->portEdit->setText(QLatin1String("127.0.0.1:50200"));
     }
+//! [create_server_0]
     ui->listenOnlyBox->setEnabled(type == Serial);
 
     if (!modbusDevice) {
         ui->connectButton->setDisabled(true);
         statusBar()->showMessage(tr("Could not create Modbus server."), 5000);
     } else {
+//! [create_server_1]
         QModbusDataUnitMap reg;
         reg.insert(QModbusDataUnit::Coils, { QModbusDataUnit::Coils, 0, 10 });
         reg.insert(QModbusDataUnit::DiscreteInputs, { QModbusDataUnit::DiscreteInputs, 0, 10 });
@@ -113,9 +116,12 @@ void MainWindow::onCurrentConnectTypeChanged(int index)
         reg.insert(QModbusDataUnit::HoldingRegisters, { QModbusDataUnit::HoldingRegisters, 0, 10 });
 
         modbusDevice->setMap(reg);
+//! [create_server_1]
 
+//! [connect_data_written]
         connect(modbusDevice, &QModbusServer::dataWritten,
                 this, &MainWindow::updateWidgets);
+//! [connect_data_written]
         connect(modbusDevice, &QModbusServer::stateChanged,
                 this, &MainWindow::onStateChanged);
         connect(modbusDevice, &QModbusServer::errorOccurred,
@@ -151,6 +157,7 @@ void MainWindow::onConnectButtonClicked()
     statusBar()->clearMessage();
 
     if (intendToConnect) {
+//! [create_server_2]
         if (static_cast<ModbusConnection>(ui->connectType->currentIndex()) == Serial) {
             modbusDevice->setConnectionParameter(QModbusDevice::SerialPortNameParameter,
                 ui->portEdit->text());
@@ -170,6 +177,7 @@ void MainWindow::onConnectButtonClicked()
             modbusDevice->setConnectionParameter(QModbusDevice::NetworkAddressParameter, url.host());
         }
         modbusDevice->setServerAddress(ui->serverEdit->text().toInt());
+//! [create_server_2]
         if (!modbusDevice->connectDevice()) {
             statusBar()->showMessage(tr("Connect failed: ") + modbusDevice->errorString(), 5000);
         } else {
@@ -211,6 +219,7 @@ void MainWindow::discreteInputChanged(int id)
     bitChanged(id, QModbusDataUnit::DiscreteInputs, button->isChecked());
 }
 
+//! [update_data_locally]
 void MainWindow::bitChanged(int id, QModbusDataUnit::RegisterType table, bool value)
 {
     if (!modbusDevice)
@@ -244,7 +253,9 @@ void MainWindow::setRegister(const QString &value)
                                      5000);
     }
 }
+//! [update_data_locally]
 
+//! [update_data_from_remote]
 void MainWindow::updateWidgets(QModbusDataUnit::RegisterType table, int address, int size)
 {
     for (int i = 0; i < size; ++i) {
@@ -265,6 +276,7 @@ void MainWindow::updateWidgets(QModbusDataUnit::RegisterType table, int address,
         }
     }
 }
+//! [update_data_from_remote]
 
 // -- private
 
diff --git a/examples/serialbus/modbus/server/mainwindow.ui b/examples/serialbus/modbus/server/mainwindow.ui
index 6b912cc..e0d847b 100644
--- a/examples/serialbus/modbus/server/mainwindow.ui
+++ b/examples/serialbus/modbus/server/mainwindow.ui
@@ -11,7 +11,7 @@
    </rect>
   </property>
   <property name="windowTitle">
-   <string>Modbus Server Example</string>
+   <string>Modbus Server</string>
   </property>
   <widget class="QWidget" name="centralWidget">
    <layout class="QVBoxLayout" name="verticalLayout">
diff --git a/src/serialbus/doc/src/qtserialbus-index.qdoc b/src/serialbus/doc/src/qtserialbus-index.qdoc
index f4af1c2..f3ae272 100644
--- a/src/serialbus/doc/src/qtserialbus-index.qdoc
+++ b/src/serialbus/doc/src/qtserialbus-index.qdoc
@@ -76,7 +76,7 @@
     \list
          \li \l {can}{CAN Bus Manager example}
          \li \l {modbus/client}{Modbus Client example}
-         \li \l {Modbus Server example}
+         \li \l {modbus/server}{Modbus Server example}
          \li \l {Modbus Custom command example}
     \endlist