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>

3 files changed, 47 insertions, 5 deletions

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}