doc++

src/modules/partition/CheckFileSystemJob.h

@@ -21,6 +21,9 @@
 
 #include <PartitionJob.h>
 
+/**
+ * Runs a file system check on an existing partition.
+ */
 class CheckFileSystemJob : public PartitionJob
 {
 public:

src/modules/partition/ColorUtils.h

@@ -22,6 +22,10 @@ class QColor;
 
 class Partition;
 
+/**
+ * Helper functions to define colors for partitions. It ensures no consecutive
+ * partitions have the same color.
+ */
 namespace ColorUtils
 {
 
@@ -29,7 +33,11 @@ QColor freeSpaceColor();
 
 QColor colorForPartition( Partition* partition );
 
-QColor colorForPartitionInFreeSpace( Partition* partition );
+/**
+ * This is similar to colorForPartition() but returns the color of a partition
+ * which would be created in freeSpacePartition
+ */
+QColor colorForPartitionInFreeSpace( Partition* freeSpacePartition );
 
 }
 

src/modules/partition/CreatePartitionDialog.h

@@ -30,6 +30,10 @@ class Partition;
 class PartitionNode;
 class Ui_CreatePartitionDialog;
 
+/**
+ * The dialog which is shown to create a new partition or to edit a
+ * to-be-created partition.
+ */
 class CreatePartitionDialog : public QDialog
 {
     Q_OBJECT
@@ -37,7 +41,15 @@ public:
     CreatePartitionDialog( Device* device, PartitionNode* parentPartition, QWidget* parentWidget = nullptr );
     ~CreatePartitionDialog();
 
-    void initFromFreeSpace( Partition* partition );
+    /**
+     * Must be called when user wants to create a partition in
+     * freeSpacePartition.
+     */
+    void initFromFreeSpace( Partition* freeSpacePartition );
+
+    /**
+     * Must be called when user wants to edit a to-be-created partition.
+     */
     void initFromPartitionToCreate( Partition* partition );
     Partition* createPartition();
 

src/modules/partition/CreatePartitionJob.h

@@ -25,6 +25,13 @@ class Device;
 class Partition;
 class FileSystem;
 
+/**
+ * Creates a partition on a device.
+ *
+ * This job does two things:
+ * 1. Create the partition
+ * 2. Create the filesystem on the partition
+ */
 class CreatePartitionJob : public PartitionJob
 {
     Q_OBJECT

src/modules/partition/CreatePartitionTableJob.h

@@ -26,6 +26,12 @@
 
 class Device;
 
+/**
+ * Creates a partition table on a device. It supports MBR and GPT partition
+ * tables.
+ *
+ * This wipes all the data from the device.
+ */
 class CreatePartitionTableJob : public Calamares::Job
 {
     Q_OBJECT

src/modules/partition/DeletePartitionJob.h

@@ -25,6 +25,13 @@ class Device;
 class Partition;
 class FileSystem;
 
+/**
+ * Deletes an existing partition.
+ *
+ * This is only used for partitions which already existed before the installer
+ * was started: partitions created within the installer and then removed are
+ * simply forgotten.
+ */
 class DeletePartitionJob : public PartitionJob
 {
     Q_OBJECT

src/modules/partition/DeviceModel.h

@@ -25,6 +25,9 @@
 class Device;
 class PartitionModel;
 
+/**
+ * A Qt model which exposes a list of Devices.
+ */
 class DeviceModel : public QAbstractListModel
 {
 public:

src/modules/partition/EditExistingPartitionDialog.h

@@ -28,6 +28,12 @@ class Partition;
 class PartitionSizeController;
 class Ui_EditExistingPartitionDialog;
 
+/**
+ * The dialog which is shown to edit a partition which already existed when the installer started.
+ *
+ * It lets you decide how to reuse the partition: whether to keep its content
+ * or reformat it, whether to resize or move it.
+ */
 class EditExistingPartitionDialog : public QDialog
 {
     Q_OBJECT

src/modules/partition/FillGlobalStorageJob.h

@@ -28,9 +28,11 @@ class Device;
 class Partition;
 
 /**
- * Fills the partitioning-related keys of GlobalStorage. Doing it after
+ * This job does not touch devices. It inserts in GlobalStorage the
- * partitioning makes it possible to access information such as the partition
+ * partition-related keys (see hacking/GlobalStorage.md)
- * device path.
+ *
+ * Inserting the keys after partitioning makes it possible to access
+ * information such as the partition path or the UUID.
  */
 class FillGlobalStorageJob : public Calamares::Job
 {

src/modules/partition/FormatPartitionJob.h

@@ -25,6 +25,12 @@ class Device;
 class Partition;
 class FileSystem;
 
+/**
+ * This job formats an existing partition.
+ *
+ * It is only used for existing partitions: newly created partitions are
+ * formatted by the CreatePartitionJob.
+ */
 class FormatPartitionJob : public PartitionJob
 {
     Q_OBJECT

src/modules/partition/MoveFileSystemJob.h

@@ -48,6 +48,12 @@ class Device;
 class Partition;
 class Report;
 
+/**
+ * This job moves the data of a filesystem from one position on the disk to
+ * another.
+ *
+ * It is used by the ResizePartitionJob.
+ */
 class MoveFileSystemJob : public PartitionJob
 {
 public:

src/modules/partition/PMUtils.h

@@ -29,15 +29,30 @@ class Partition;
 class PartitionNode;
 class PartitionRole;
 
+/**
+ * Helper functions to manipulate partitions
+ */
 namespace PMUtils
 {
 
 bool isPartitionFreeSpace( Partition* );
 
+/**
+ * Returns true if the partition is planned to be created by the installer as
+ * opposed to already existing on the disk.
+ */
 bool isPartitionNew( Partition* );
 
+/**
+ * Iterates on all devices and return the first partition which is associated
+ * with mountPoint. This uses PartitionInfo::mountPoint(), not Partition::mountPoint()
+ */
 Partition* findPartitionByMountPoint( const QList< Device* >& devices, const QString& mountPoint );
 
+/**
+ * Helper function to create a new Partition object (does not create anything
+ * on the disk) associated with a FileSystem.
+ */
 Partition* createNewPartition( PartitionNode* parent, const Device& device, const PartitionRole& role, FileSystem::Type fsType, qint64 firstSector, qint64 lastSector );
 
 Partition* clonePartition( Device* device, Partition* partition );

src/modules/partition/PartitionCoreModule.h

@@ -39,7 +39,11 @@ class Partition;
 class QStandardItemModel;
 
 /**
- * Owns the Qt models and the PM devices
+ * The core of the module.
+ *
+ * It has two responsibilities:
+ * - Listing the devices and partitions, creating Qt models for them.
+ * - Creating jobs for any changes requested by the user interface.
  */
 class PartitionCoreModule : public QObject
 {

src/modules/partition/PartitionInfo.h

@@ -24,8 +24,17 @@
 class Partition;
 
 /**
- * Functions to store Calamares-specific info in the Qt properties of a
+ * Functions to store Calamares-specific information in the Qt properties of a
  * Partition object.
+ *
+ * See README.md for the rational behind this design.
+ *
+ * Properties:
+ * - mountPoint: which directory will a partition be mounted on the installed
+ *   system. This is different from Partition::mountPoint, which is the
+ *   directory on which a partition is *currently* mounted while the installer
+ *   is running.
+ * - format: whether this partition should be formatted at install time.
  */
 namespace PartitionInfo
 {
@@ -38,6 +47,11 @@ void setFormat( Partition* partition, bool value );
 
 void reset( Partition* partition );
 
+/**
+ * Returns true if one of the property has been set. This information is used
+ * by the UI to decide whether the "Revert" button should be enabled or
+ * disabled.
+ */
 bool isDirty( Partition* partition );
 
 };

src/modules/partition/PartitionJob.h

@@ -24,7 +24,7 @@
 class Partition;
 
 /**
- * Base class for jobs which affect a partition
+ * Base class for jobs which affect a partition.
  */
 class PartitionJob : public Calamares::Job
 {

src/modules/partition/PartitionModel.h

@@ -25,6 +25,20 @@ class Device;
 class Partition;
 class PartitionNode;
 
+/**
+ * A Qt tree model which exposes the partitions of a device.
+ *
+ * Its depth is only more than 1 if the device has extended partitions.
+ *
+ * Note on updating:
+ *
+ * The Device class does not notify the outside world of changes on the
+ * Partition objects it owns. Since a Qt model must notify its views *before*
+ * and *after* making changes, it is important to make use of
+ * the PartitionModel::ResetHelper class to wrap changes.
+ *
+ * This is what PartitionCoreModule does when it create jobs.
+ */
 class PartitionModel : public QAbstractItemModel
 {
 public:
@@ -69,6 +83,7 @@ public:
      */
     void init( Device* device );
 
+    // QAbstractItemModel API
     QModelIndex index( int row, int column, const QModelIndex& parent = QModelIndex() ) const override;
     QModelIndex parent( const QModelIndex& child ) const override;
     int columnCount( const QModelIndex& parent = QModelIndex() ) const override;

src/modules/partition/PartitionPage.h

@@ -29,6 +29,12 @@ class Device;
 class DeviceModel;
 class Partition;
 
+/**
+ * The user interface for the module.
+ *
+ * Shows the information exposed by PartitionCoreModule and asks it to schedule
+ * jobs according to user actions.
+ */
 class PartitionPage : public QWidget
 {
     Q_OBJECT

src/modules/partition/PartitionPreview.h

@@ -20,6 +20,13 @@
 
 #include <QAbstractItemView>
 
+/**
+ * A Qt model view which displays the partitions inside a device as a colored bar.
+ *
+ * It has been created to be used with a PartitionModel instance, but does not
+ * call any PartitionModel-specific methods: it should be usable with other
+ * models as long as they provide the same roles PartitionModel provides.
+ */
 class PartitionPreview : public QAbstractItemView
 {
 public:

src/modules/partition/PartitionSizeController.h

@@ -30,7 +30,8 @@ class Partition;
 class PartResizerWidget;
 
 /**
- * Synchronize a PartResizerWidget and a QSpinBox
+ * Synchronizes a PartResizerWidget and a QSpinBox, making sure any change made
+ * to one is reflected in the other.
  */
 class PartitionSizeController : public QObject
 {

src/modules/partition/PartitionViewStep.h

@@ -27,6 +27,10 @@
 class PartitionPage;
 class PartitionCoreModule;
 
+/**
+ * The starting point of the module. Instantiates PartitionCoreModule and
+ * PartitionPage, then connect them.
+ */
 class PLUGINDLLEXPORT PartitionViewStep : public Calamares::ViewStep
 {
     Q_OBJECT

src/modules/partition/ResizePartitionJob.h

@@ -25,6 +25,11 @@ class Device;
 class Partition;
 class FileSystem;
 
+/**
+ * This job resizes an existing partition.
+ *
+ * It can grow, shrink and/or move a partition while preserving its content.
+ */
 class ResizePartitionJob : public PartitionJob
 {
     Q_OBJECT