Docs: document Device (a description) and CoreBackendDevice (an operational class)

src/backend/corebackend.h

@@ -93,6 +93,8 @@ public:
       *         not, including CD ROM devices, are returned.
       * @return a QList of pointers to Device instances. The caller is responsible
       *         for deleting these objects.
+      * @note A Device object is a description of the device, not
+      *         an object to operate on. See openDevice().
       */
     virtual QList<Device*> scanDevices(bool excludeReadOnly = false) = 0;
 

src/backend/corebackenddevice.h

@@ -30,7 +30,11 @@ class PartitionTable;
 class Report;
 
 /**
-  * Interface class representing a device in the backend plugin.
+  * Interface class for devices in the backend plugin.
+  * For a device description, see Device. This
+  * CoreBackendDevice can be used for (read- and) write
+  * operations on the raw device.
+  *
   * @author Volker Lanz <vl@fidra.de>
   */
 class LIBKPMCORE_EXPORT CoreBackendDevice

src/core/device.h

@@ -29,9 +29,11 @@ class CreatePartitionTableOperation;
 class CoreBackend;
 class SmartStatus;
 
-/** A abstract device interface.
+/** A device description.
 
-    Represents a device like /dev/sda.
+    Represents a device like /dev/sda. Contains information about
+    the device (name, status, size ..) but does not operate on
+    the device itself. @see CoreBackendDevice
 
     Devices are the outermost entity; they contain a PartitionTable that itself contains Partitions.
 
@@ -104,6 +106,11 @@ public:
         return *m_SmartStatus;
     }
 
+    /**
+     * Change the description of the partition table for different one.
+     * The device itself is not changed; use CreatePartitionTableOperation
+     * for that. The Device instance becomes the owner of @p ptable .
+     */
     virtual void setPartitionTable(PartitionTable* ptable) {
         m_PartitionTable = ptable;
     }