More documentations.

src/core/lvmdevice.cpp

@@ -33,7 +33,7 @@
 #include <KLocalizedString>
 #include <KMountPoint>
 
-/** Constructs a representation of LVM device with functionning LV as Partitions
+/** Constructs a representation of LVM device with initialized LV as Partitions
  *
  *  @param vgName Volume Group name
  *  @param iconName Icon representing LVM Volume group
@@ -58,6 +58,10 @@ LvmDevice::LvmDevice(const QString& vgName, const QString& iconName)
     initPartitions();
 }
 
+/**
+ * shared list of PV's paths that will be added to any VGs.
+ * (have been added to an operation, but not yet applied)
+*/
 QStringList LvmDevice::s_DirtyPVs;
 
 LvmDevice::~LvmDevice()
@@ -84,7 +88,7 @@ void LvmDevice::initPartitions()
 }
 
 /**
- *  @return sorted Partition(LV) Array
+ *  @return a initialized Partition(LV) list
  */
 const QList<Partition*> LvmDevice::scanPartitions(PartitionTable* pTable) const
 {
@@ -95,23 +99,22 @@ const QList<Partition*> LvmDevice::scanPartitions(PartitionTable* pTable) const
     return pList;
 }
 
-/**
+/** scan and construct a partition(LV) at a given path
+ *
+ * NOTE:
+ * LVM partition has 2 different start and end sector values
+ * 1. representing the actual LV start from 0 -> size of LV - 1
+ * 2. representing abstract LV's sector inside a VG partitionTable
+ *    start from last sector + 1 of last Partitions -> size of LV - 1
+ * Reason for this is for the LV Partition to work nicely with other parts of the codebase
+ * without too many special cases.
+ *
  * @param lvPath LVM Logical Volume path
  * @param pTable Abstract partition table representing partitions of LVM Volume Group
- * @return sorted Partition (LV) Array
+ * @return initialized Partition(LV)
  */
 Partition* LvmDevice::scanPartition(const QString& lvPath, PartitionTable* pTable) const
 {
-    /*
-     * NOTE:
-     * LVM partition has 2 different start and end sector values
-     * 1. representing the actual LV start from 0 -> size of LV - 1
-     * 2. representing abstract LV's sector inside a VG partitionTable
-     *    start from last sector + 1 of last Partitions -> size of LV - 1
-     * Reason for this is for the LV Partition to work nicely with other parts of the codebase
-     * without too many special cases.
-     */
-
     activateLV(lvPath);
 
     qint64 lvSize = getTotalLE(lvPath);
@@ -187,8 +190,9 @@ Partition* LvmDevice::scanPartition(const QString& lvPath, PartitionTable* pTabl
     return part;
 }
 
-/**
+/** scan and contruct list of initialized LvmDevice objects.
  *
+ *  @return list of initialized LvmDevice
  */
 QList<LvmDevice*> LvmDevice::scanSystemLVM()
 {

src/core/lvmdevice.h

@@ -32,12 +32,11 @@ class Report;
 class Partition;
 class SmartStatus;
 
-/** Represents LVM Volume Group.
+/** Representation of LVM Volume Group(VG).
 
     Devices are the outermost entity; they contain a PartitionTable that itself contains Partitions.
 
-    @see PartitionTable, Partition
+    @see Device, VolumeManagerDevice, PartitionTable, Partition
-    @author Volker Lanz <vl@fidra.de>
 */
 class LIBKPMCORE_EXPORT LvmDevice : public VolumeManagerDevice
 {
@@ -56,9 +55,6 @@ public:
 
 public:
 
-    /**
-     *
-     */
     static QList<LvmDevice*> scanSystemLVM();
 
     static const QStringList getVGs();
@@ -93,15 +89,7 @@ public:
 protected:
 
     void initPartitions() override;
-
-    /**
-     *
-     */
     const QList<Partition*> scanPartitions(PartitionTable* pTable) const;
-
-    /**
-     *
-     */
     Partition* scanPartition(const QString& lvPath, PartitionTable* pTable) const;
     qint64 mappedSector(const QString& lvPath, qint64 sector) const override;
 

src/core/volumemanagerdevice.cpp

@@ -17,7 +17,8 @@
 
 #include "core/volumemanagerdevice.h"
 
-/** Constructs a Volume Manager Device with an empty PartitionTable.
+/** Constructs an abstract Volume Manager Device with an empty PartitionTable.
+ *
 */
 VolumeManagerDevice::VolumeManagerDevice(const QString& name,
                                          const QString& deviceNode,

src/core/volumemanagerdevice.h

@@ -27,52 +27,56 @@
 #include <QObject>
 #include <QtGlobal>
 
-/** A Volume Manager of real physical devices represented as an abstract device.
+/** A Volume Manager of physical devices represented as an abstract device.
-
+ *
-    VolumeManagerDevice is an abstract class of volume manager. e.g: LVM, SoftRAID.
+ *   VolumeManagerDevice is an abstract device class for volume manager. e.g: LVM, SoftRAID.
-    a device like /dev/sda, /dev/sdb1.
+ *   example of physical device: /dev/sda, /dev/sdb1.
-
+ *
-    Devices are the outermost entity; they contain a PartitionTable that itself contains Partitions.
+ *   Devices are the outermost entity; they contain a PartitionTable that itself contains Partitions.
-
+ *
-    @see PartitionTable, Partition
+ *   @see Device, PartitionTable, Partition
-*/
+ */
 class LIBKPMCORE_EXPORT VolumeManagerDevice : public Device
 {
     Q_DISABLE_COPY(VolumeManagerDevice)
 
 public:
 
-    /**
-     *
-     */
     VolumeManagerDevice(const QString& name, const QString& deviceNode, const qint32 logicalSize, const qint64 totalLogical, const QString& iconName = QString(), Device::Type type = Device::Unknown_Device);
 
     /**
-     *  @return list of physical device or partitions that makes up volumeManagerDevice.
+     *  @return list of physical device's path that makes up volumeManagerDevice.(e.g: /dev/sda, /dev/sdb1)
      */
     virtual const QStringList deviceNodes() const = 0;
 
     /**
-     *
+     * @return list of logical partition's path.
      */
-    virtual const QStringList partitionNodes() const = 0; /** Return list of partitions on the device. */
+    virtual const QStringList partitionNodes() const = 0;
 
     /**
-     *
+     * @return size of logical partition at the given path in bytes.
      */
-    virtual qint64 partitionSize(QString& partitionPath) const = 0; /** Return size of provided partition in bytes. */
+    virtual qint64 partitionSize(QString& partitionPath) const = 0;
 
 protected:
 
-    /**
+    /** Initialize device's partition table and partitions.
      *
      */
     virtual void initPartitions() = 0;
 
-    /**
+    /** absolute sector as represented inside the device's partitionTable
      *
+     *  For VolumeMangerDevice to works with the rest of the codebase, partitions are stringed
+     *  one after another to create a representation of PartitionTable and partition just like
+     *  real disk device.
+     *
+     *  @param partitionPath logical partition path
+     *  @sector sector value to be mapped (if 0, will return start sector of the partition)
+     *  @return absolute sector value as represented inside device's partitionTable
      */
-    virtual qint64  mappedSector(const QString& devNode, qint64 sector) const = 0;
+    virtual qint64  mappedSector(const QString& partitionPath, qint64 sector) const = 0;
 
 public:
 

src/fs/lvm2_pv.cpp

@@ -281,7 +281,13 @@ qint64 lvm2_pv::getPESize(const QString& deviceNode)
     return val.isEmpty() ? -1 : val.toLongLong();
 }
 
-QString  lvm2_pv::getpvField(const QString& fieldname, const QString& deviceNode)
+/** Get pvs command output with field name
+ *
+ *  @param fieldName LVM field name
+ *  @param deviceNode path to PV
+ *  @return raw output of pvs command, usually with many spaces
+ */
+QString  lvm2_pv::getpvField(const QString& fieldName, const QString& deviceNode)
 {
     QStringList args = { QStringLiteral("pvs"),
                     QStringLiteral("--foreign"),
@@ -291,7 +297,7 @@ QString  lvm2_pv::getpvField(const QString& fieldname, const QString& deviceNode
                     QStringLiteral("B"),
                     QStringLiteral("--nosuffix"),
                     QStringLiteral("--options"),
-                    fieldname };
+                    fieldName };
     if (!deviceNode.isEmpty()) {
         args << deviceNode;
     }

src/fs/lvm2_pv.h

@@ -113,7 +113,7 @@ public:
     static bool isUsed(const QString& pvNode);
 
     static QString getVGName(const QString& deviceNode);
-    static QString getpvField(const QString& fieldname, const QString& deviceNode = QString());
+    static QString getpvField(const QString& fieldName, const QString& deviceNode = QString());
 
     static const QStringList getFreePV();
 

src/ops/deactivatevolumegroupoperation.cpp

@@ -59,6 +59,11 @@ void DeactivateVolumeGroupOperation::undo()
     }
 }
 
+/** loop through given device's partitions to check if any is mounted.
+ *
+ *  @dev VolumeManagerDevice with initialized partitions
+ *  @return false if any of the device's partition is mounted.
+ */
 bool DeactivateVolumeGroupOperation::isDeactivatable(const VolumeManagerDevice* dev)
 {
     if (dev->type() == Device::LVM_Device) {