From c4ae5d680c0f3ed29018f86ce9b02b2ba158a93a Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Tue, 3 Oct 2017 05:23:10 -0400
Subject: [PATCH] Docs: document Device (a description) and CoreBackendDevice
 (an operational class)

---
 src/backend/corebackend.h       |  2 ++
 src/backend/corebackenddevice.h |  6 +++++-
 src/core/device.h               | 11 +++++++++--
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/backend/corebackend.h b/src/backend/corebackend.h
index 4210965..738cf1c 100644
--- a/src/backend/corebackend.h
+++ b/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;
 
diff --git a/src/backend/corebackenddevice.h b/src/backend/corebackenddevice.h
index b35adc8..cd8c835 100644
--- a/src/backend/corebackenddevice.h
+++ b/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
diff --git a/src/core/device.h b/src/core/device.h
index 7a6968b..a32f77b 100644
--- a/src/core/device.h
+++ b/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;
     }