From 28dd42839db8999107e00e4f5db6f05c17cbe637 Mon Sep 17 00:00:00 2001 From: Chantara Tith Date: Mon, 15 Aug 2016 13:18:40 +0700 Subject: [PATCH] More documentations. --- src/core/lvmdevice.cpp | 34 +++++++++-------- src/core/lvmdevice.h | 16 +------- src/core/volumemanagerdevice.cpp | 3 +- src/core/volumemanagerdevice.h | 44 ++++++++++++---------- src/fs/lvm2_pv.cpp | 10 ++++- src/fs/lvm2_pv.h | 2 +- src/ops/deactivatevolumegroupoperation.cpp | 5 +++ 7 files changed, 61 insertions(+), 53 deletions(-) diff --git a/src/core/lvmdevice.cpp b/src/core/lvmdevice.cpp index 3b25398..3c8e95e 100644 --- a/src/core/lvmdevice.cpp +++ b/src/core/lvmdevice.cpp @@ -33,7 +33,7 @@ #include #include -/** 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 LvmDevice::scanPartitions(PartitionTable* pTable) const { @@ -95,23 +99,22 @@ const QList 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::scanSystemLVM() { diff --git a/src/core/lvmdevice.h b/src/core/lvmdevice.h index 006fc29..f2bddb0 100644 --- a/src/core/lvmdevice.h +++ b/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 - @author Volker Lanz + @see Device, VolumeManagerDevice, PartitionTable, Partition */ class LIBKPMCORE_EXPORT LvmDevice : public VolumeManagerDevice { @@ -56,9 +55,6 @@ public: public: - /** - * - */ static QList scanSystemLVM(); static const QStringList getVGs(); @@ -93,15 +89,7 @@ public: protected: void initPartitions() override; - - /** - * - */ const QList scanPartitions(PartitionTable* pTable) const; - - /** - * - */ Partition* scanPartition(const QString& lvPath, PartitionTable* pTable) const; qint64 mappedSector(const QString& lvPath, qint64 sector) const override; diff --git a/src/core/volumemanagerdevice.cpp b/src/core/volumemanagerdevice.cpp index 94fbe6f..b4b4def 100644 --- a/src/core/volumemanagerdevice.cpp +++ b/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, diff --git a/src/core/volumemanagerdevice.h b/src/core/volumemanagerdevice.h index 550b49a..fad70da 100644 --- a/src/core/volumemanagerdevice.h +++ b/src/core/volumemanagerdevice.h @@ -27,52 +27,56 @@ #include #include -/** A Volume Manager of real physical devices represented as an abstract device. - - VolumeManagerDevice is an abstract class of volume manager. e.g: LVM, SoftRAID. - a device like /dev/sda, /dev/sdb1. - - Devices are the outermost entity; they contain a PartitionTable that itself contains Partitions. - - @see PartitionTable, Partition -*/ +/** A Volume Manager of physical devices represented as an abstract device. + * + * VolumeManagerDevice is an abstract device class for volume manager. e.g: LVM, SoftRAID. + * example of physical device: /dev/sda, /dev/sdb1. + * + * Devices are the outermost entity; they contain a PartitionTable that itself contains Partitions. + * + * @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: diff --git a/src/fs/lvm2_pv.cpp b/src/fs/lvm2_pv.cpp index 34b3c5a..1543a59 100644 --- a/src/fs/lvm2_pv.cpp +++ b/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; } diff --git a/src/fs/lvm2_pv.h b/src/fs/lvm2_pv.h index 5fca3b3..3f86185 100644 --- a/src/fs/lvm2_pv.h +++ b/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(); diff --git a/src/ops/deactivatevolumegroupoperation.cpp b/src/ops/deactivatevolumegroupoperation.cpp index 1cf4248..8922696 100644 --- a/src/ops/deactivatevolumegroupoperation.cpp +++ b/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) {