CAN Manager Example: extend documentation

Extend the documentation so that it actually highlights the main
features shown by the example.

Also update the documentation to match the guidelines:
* update screenshot
* add Connectivity category

Task-number: QTBUG-110890
Change-Id: I9c75488440be23885c7751f6d00018e9537cdfa2
Reviewed-by: André Hartmann <aha_1980@gmx.de>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
(cherry picked from commit be1a4f7e32503a9de156a454ccd9c6e99f79e4a9)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

5 files changed, 57 insertions, 5 deletions

diff --git a/examples/serialbus/can/mainwindow.cpp b/examples/serialbus/can/mainwindow.cpp
index 1f89bcb..3234043 100644
--- a/examples/serialbus/can/mainwindow.cpp
+++ b/examples/serialbus/can/mainwindow.cpp
@@ -107,9 +107,11 @@ void MainWindow::connectDevice()
     else
         m_model->setQueueLimit(0);
 
+//! [create_can_device_0]
     QString errorString;
     m_canDevice.reset(QCanBus::instance()->createDevice(p.pluginName, p.deviceInterfaceName,
                                                         &errorString));
+//! [create_can_device_0]
     if (!m_canDevice) {
         m_status->setText(tr("Error creating device '%1', reason: '%2'")
                           .arg(p.pluginName, errorString));
@@ -118,12 +120,14 @@ void MainWindow::connectDevice()
 
     m_numberFramesWritten = 0;
 
+//! [create_can_device_1]
     connect(m_canDevice.get(), &QCanBusDevice::errorOccurred,
             this, &MainWindow::processErrors);
     connect(m_canDevice.get(), &QCanBusDevice::framesReceived,
             this, &MainWindow::processReceivedFrames);
     connect(m_canDevice.get(), &QCanBusDevice::framesWritten,
             this, &MainWindow::processFramesWritten);
+//! [create_can_device_1]
 
     if (p.useConfigurationEnabled) {
         for (const ConnectDialog::ConfigurationItem &item : p.configurations)
@@ -244,6 +248,7 @@ void MainWindow::processReceivedFrames()
     if (!m_canDevice)
         return;
 
+//! [receive_can_frame]
     while (m_canDevice->framesAvailable()) {
         m_numberFramesReceived++;
         const QCanBusFrame frame = m_canDevice->readFrame();
@@ -266,6 +271,7 @@ void MainWindow::processReceivedFrames()
         m_model->appendFrame(QStringList({QString::number(m_numberFramesReceived),
                                           time, flags, id, dlc, data}));
     }
+//! [receive_can_frame]
 }
 
 void MainWindow::sendFrame(const QCanBusFrame &frame) const
@@ -273,7 +279,9 @@ void MainWindow::sendFrame(const QCanBusFrame &frame) const
     if (!m_canDevice)
         return;
 
+//! [send_can_frame]
     m_canDevice->writeFrame(frame);
+//! [send_can_frame]
 }
 
 void MainWindow::onAppendFramesTimeout()
diff --git a/examples/serialbus/can/sendframebox.cpp b/examples/serialbus/can/sendframebox.cpp
index e26524e..4f6025f 100644
--- a/examples/serialbus/can/sendframebox.cpp
+++ b/examples/serialbus/can/sendframebox.cpp
@@ -208,6 +208,7 @@ SendFrameBox::SendFrameBox(QWidget *parent) :
     frameIdOrPayloadChanged();
 
     connect(m_ui->sendButton, &QPushButton::clicked, [this]() {
+    //! [prepare_can_frame]
         const uint frameId = m_ui->frameIdEdit->text().toUInt(nullptr, 16);
         QString data = m_ui->payloadEdit->text();
         m_ui->payloadEdit->setText(formatHexData(data));
@@ -222,6 +223,7 @@ SendFrameBox::SendFrameBox(QWidget *parent) :
             frame.setFrameType(QCanBusFrame::ErrorFrame);
         else if (m_ui->remoteFrame->isChecked())
             frame.setFrameType(QCanBusFrame::RemoteRequestFrame);
+    //! [prepare_can_frame]
 
         emit sendFrame(frame);
     });
diff --git a/src/serialbus/doc/images/can-example.png b/src/serialbus/doc/images/can-example.png
index 4b44819..4e31331 100644
--- a/src/serialbus/doc/images/can-example.png
+++ b/src/serialbus/doc/images/can-example.png
diff --git a/src/serialbus/doc/src/examples/can.qdoc b/src/serialbus/doc/src/examples/can.qdoc
index fdb946a..26e9ba9 100644
--- a/src/serialbus/doc/src/examples/can.qdoc
+++ b/src/serialbus/doc/src/examples/can.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 can
-    \title CAN Bus example
+    \title CAN Bus Manager
+    \ingroup qtserialbus-examples
+    \meta category Connectivity
 
     \brief The example sends and receives CAN bus frames.
 
@@ -10,8 +12,6 @@
     are ordered according to their type. A connect dialog is
     provided to adjust the CAN Bus connection parameters.
 
-    \ingroup qtserialbus-examples
-
     Key \l{Qt Serial Bus} classes used in this example:
 
     \list
@@ -21,5 +21,47 @@
 
     \image ../images/can-example.png
 
+    \section1 Creating a QCanBusDevice
+
+    An instance of \l QCanBusDevice is required to perform any CAN
+    communication.
+
+    The \c ConnectDialog allows to specify all the required parameters. After
+    that the device is created using the provided plugin and interface names:
+
+    \snippet can/mainwindow.cpp create_can_device_0
+    \snippet can/mainwindow.cpp create_can_device_1
+
+    The established connections allow to process incoming frames, control the
+    sent frames and handle errors.
+
+    When the device is created, use \l QCanBusDevice::connectDevice() to
+    start the communication.
+
+    \section1 Processing Incoming Frames
+
+    \l QCanBusDevice emits a \l {QCanBusDevice::}{framesReceived()} signal when
+    new frames are available. The \l {QCanBusDevice::}{readFrame()} method
+    can be used to read a single \l QCanBusFrame while there are
+    \l {QCanBusDevice::framesAvailable}{available frames}. Once the frame is
+    received, individual parameters such as \l {QCanBusFrame::}{frameId},
+    \l {QCanBusFrame::}{timeStamp}, or \l {QCanBusFrame::}{payload} can be
+    extracted from it:
+
+    \snippet can/mainwindow.cpp receive_can_frame
+
+    \section1 Sending Frames
+
+    To send custom data over the CAN bus, the user needs to provide at least
+    a \l {QCanBusFrame::}{frameId} and a \l {QCanBusFrame::}{payload}.
+    Optionally other \l QCanBusFrame parameters can be configured:
+
+    \snippet can/sendframebox.cpp prepare_can_frame
+
+    Once the frame is prepared, the \l QCanBusDevice::writeFrame() method can
+    be used to send it:
+
+    \snippet can/mainwindow.cpp send_can_frame
+
     \include examples-run.qdocinc
 */
diff --git a/src/serialbus/doc/src/qtserialbus-index.qdoc b/src/serialbus/doc/src/qtserialbus-index.qdoc
index fe830ce..fd4c1cf 100644
--- a/src/serialbus/doc/src/qtserialbus-index.qdoc
+++ b/src/serialbus/doc/src/qtserialbus-index.qdoc
@@ -74,7 +74,7 @@
     \section1 Examples
 
     \list
-         \li \l {CAN Bus Example}
+         \li \l {can}{CAN Bus Manager example}
          \li \l {Modbus Client example}
          \li \l {Modbus Server example}
          \li \l {Modbus Custom command example}