Doc: Improve plugin overview pages

* Rename "backend" to "plugin" for consistence
* Improve the connection snippets regarding error handling
* Add a hint to QCanBus::availableDevices()

Change-Id: I6fc24add5f9cb34e9ffad8b58f6134124f456cdd
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
Reviewed-by: Denis Shienkov <denis.shienkov@gmail.com>

5 files changed, 57 insertions, 23 deletions

diff --git a/src/serialbus/doc/src/passthrucan.qdoc b/src/serialbus/doc/src/passthrucan.qdoc
index 21e6283..eff2ef7 100644
--- a/src/serialbus/doc/src/passthrucan.qdoc
+++ b/src/serialbus/doc/src/passthrucan.qdoc
@@ -99,9 +99,13 @@
     signal:
 
     \code
-        connect(device, &QCanBusDevice::stateChanged,
-                this, &MyClass::canStateChanged);
-        device->connectDevice();
+        if (!device) {
+            // Error handling goes here
+        } else {
+            connect(device, &QCanBusDevice::stateChanged,
+                    this, &MyClass::canStateChanged);
+            device->connectDevice();
+        }
     \endcode
 
     \l {QCanBusDevice::}{state()} will return \l {QCanBusDevice::}{ConnectedState}
diff --git a/src/serialbus/doc/src/peakcan.qdoc b/src/serialbus/doc/src/peakcan.qdoc
index 8b64c0a..68d52fd 100644
--- a/src/serialbus/doc/src/peakcan.qdoc
+++ b/src/serialbus/doc/src/peakcan.qdoc
@@ -33,8 +33,8 @@
     The PeakCAN plugin encapsulates the low-level API to work with the
     \l{http://www.peak-system.com/}{PEAK-System} CAN adapters.
 
-    This plugin requires the PCAN device drivers and the pcanbasic library
-    (pcanbasic.dll under Windows).
+    This plugin requires the PCAN device drivers and the PCAN-Basic library
+    (pcanbasic.dll under Windows, libpcanbasic.so under Linux).
 
     \section1 Creating CAN Bus Devices
 
@@ -51,14 +51,21 @@
     Next, a connection to a specific interface can be established:
 
     \code
+        QString errorString;
         QCanBusDevice *device = QCanBus::instance()->createDevice(
-            QStringLiteral("peakcan"), QStringLiteral("usb0"));
-        device->connectDevice();
+            QStringLiteral("peakcan"), QStringLiteral("usb0"), &errorString);
+        if (!device) {
+            // Error handling goes here
+            qDebug << errorString;
+        } else {
+            device->connectDevice();
+        }
     \endcode
 
     Where \e usb0 is the active CAN interface name. The PeakCAN plugin supports
     16 USB interfaces from \e usb0 to \e usb15 and 16 PCI interfaces from
-    \e pci0 to \e pci15.
+    \e pci0 to \e pci15. The \l {QCanBus::}{availableDevices()} method returns a
+    list of currently available devices.
 
     \note Only the USB and PCI adapters are currently supported by this plugin.
 
diff --git a/src/serialbus/doc/src/socketcan.qdoc b/src/serialbus/doc/src/socketcan.qdoc
index a7cac9f..df58dae 100644
--- a/src/serialbus/doc/src/socketcan.qdoc
+++ b/src/serialbus/doc/src/socketcan.qdoc
@@ -111,13 +111,21 @@
     Next, a connection to a specific interface can be established:
 
     \code
+        QString errorString;
         QCanBusDevice *device = QCanBus::instance()->createDevice(
-            QStringLiteral("socketcan"), QStringLiteral("can0"));
-        device->connectDevice();
+            QStringLiteral("socketcan"), QStringLiteral("can0"), &errorString);
+        if (!device) {
+            // Error handling goes here
+            qDebug << errorString;
+        } else {
+            device->connectDevice();
+        }
     \endcode
 
     Where \e can0 is the active CAN interface name. CAN interfaces act like regular
     network interfaces on Linux systems and can be discovered using \c ifconfig.
+    Also, the \l {QCanBus::}{availableDevices()} method returns a list of currently
+    available devices.
 
     The device is now open for writing and reading CAN frames:
 
diff --git a/src/serialbus/doc/src/systeccan.qdoc b/src/serialbus/doc/src/systeccan.qdoc
index bd8ee61..af34665 100644
--- a/src/serialbus/doc/src/systeccan.qdoc
+++ b/src/serialbus/doc/src/systeccan.qdoc
@@ -26,11 +26,11 @@
 ****************************************************************************/
 /*!
     \page qtserialbus-SystecCAN-overview.html
-    \title Using SystecCAN Backend
+    \title Using SystecCAN Plugin
 
-    \brief Overview of how to use the SystecCAN backend.
+    \brief Overview of how to use the SystecCAN plugin.
 
-    The SystecCAN backend encapsulates the low-level API to work with the
+    The SystecCAN plugin encapsulates the low-level API to work with the
     \l{http://www.systec-electronic.com/}{SYS TEC} CAN adapters.
 
     This plugin requires the SYS TEC CAN device drivers and the usbcan32.dll
@@ -38,28 +38,36 @@
 
     \section1 Creating CAN Bus Devices
 
-    At first it is necessary to check that QCanBus provides the desired backend:
+    At first it is necessary to check that QCanBus provides the desired plugin:
 
     \code
         if (QCanBus::instance()->plugins().contains(QStringLiteral("systeccan"))) {
-            // backend available
+            // plugin available
         }
     \endcode
 
-    Where \e systeccan is the backend name.
+    Where \e systeccan is the plugin name.
 
     Next, a connection to a specific interface can be established:
 
     \code
+        QString errorString;
         QCanBusDevice *device = QCanBus::instance()->createDevice(
-            QStringLiteral("systeccan"), QStringLiteral("can0.0"));
-        device->connectDevice();
+            QStringLiteral("systeccan"), QStringLiteral("can0.0"), &errorString);
+        if (!device) {
+            // Error handling goes here
+            qDebug << errorString;
+        } else {
+            device->connectDevice();
+        }
+
     \endcode
 
     Where, \e can0.0 is the active CAN interface name (interface 0, channel 0).
-    The SystecCAN backend supports 64 USB interfaces (so called modules) from
+    The SystecCAN plugin supports 64 USB interfaces (so called modules) from
     \e can0.0 to \e can63.1. Each module can have one or two channels, they can
-    be accessed by the index canX.0 or canX.1.
+    be accessed by the index canX.0 or canX.1. The \l {QCanBus::}{availableDevices()}
+    method returns a list of currently available devices.
 
     \note SYS TEC also provides 8 or 16 channel CAN interfaces. These units
     consist of an USB hub and multiple two-channel modules internally.
diff --git a/src/serialbus/doc/src/vectorcan.qdoc b/src/serialbus/doc/src/vectorcan.qdoc
index 5b23c8e..eb4acdd 100644
--- a/src/serialbus/doc/src/vectorcan.qdoc
+++ b/src/serialbus/doc/src/vectorcan.qdoc
@@ -51,9 +51,15 @@
     Next, a connection to a specific interface can be established:
 
     \code
+        QString errorString;
         QCanBusDevice *device = QCanBus::instance()->createDevice(
-            QStringLiteral("vectorcan"), QStringLiteral("can0"));
-        device->connectDevice();
+            QStringLiteral("vectorcan"), QStringLiteral("can0"), &errorString);
+        if (!device) {
+            // Error handling goes here
+            qDebug << errorString;
+        } else {
+            device->connectDevice();
+        }
     \endcode
 
     Where \e can0 is the active CAN channel name. The VectorCAN plugin provides
@@ -61,7 +67,8 @@
     to \e can63. Some of these channels can be virtual, and therefore can be used
     without actual CAN hardware. To find out the virtual channels, the program
     "Vector Hardware Config" (vcanconf.exe) can be used, which is included in
-    Vector's driver package.
+    Vector's driver package. The \l {QCanBus::}{availableDevices()} method returns
+    a list of currently available devices.
 
     The device is now open for writing and reading CAN frames: