Documentation++

src/modules/partition/core/PartitionActions.h

@@ -27,10 +27,25 @@ class Partition;
 
 namespace PartitionActions
 {
+
+/**
+ * @brief doAutopartition sets up an autopartitioning operation on the given Device.
+ * @param core a pointer to the PartitionCoreModule instance.
+ * @param dev the device to wipe.
+ * @param luksPassphrase the passphrase for LUKS encryption (optional, default is empty).
+ */
 void doAutopartition( PartitionCoreModule* core,
                       Device* dev,
                       const QString& luksPassphrase = QString() );
 
+/**
+ * @brief doReplacePartition sets up replace-partitioning with the given partition.
+ * @param core a pointer to the PartitionCoreModule instance.
+ * @param dev a pointer to the Device on which to replace a partition.
+ * @param partition a pointer to the Partition to be replaced.
+ * @param luksPassphrase the passphrase for LUKS encryption (optional, default is empty).
+ * @note this function also takes care of requesting PCM to delete the partition.
+ */
 void doReplacePartition( PartitionCoreModule* core,
                          Device* dev,
                          Partition* partition,

src/modules/partition/core/PartitionCoreModule.h

@@ -53,6 +53,11 @@ class PartitionCoreModule : public QObject
 {
     Q_OBJECT
 public:
+    /**
+     * @brief The SummaryInfo struct is a wrapper for PartitionModel instances for
+     * a given Device.
+     * Each Device gets a mutable "after" model and an immutable "before" model.
+     */
     struct SummaryInfo
     {
         QString deviceName;
@@ -64,21 +69,41 @@ public:
     PartitionCoreModule( QObject* parent = nullptr );
     ~PartitionCoreModule();
 
+    /**
+     * @brief init performs a devices scan and initializes all KPMcore data
+     * structures.
+     * This function is thread safe.
+     */
     void init();
 
+    /**
+     * @brief deviceModel returns a model which exposes a list of available
+     * storage devices.
+     * @return the device model.
+     */
     DeviceModel* deviceModel() const;
 
+    /**
+     * @brief partitionModelForDevice returns the PartitionModel for the given device.
+     * @param device the device for which to get a model.
+     * @return a PartitionModel which represents the partitions of a device.
+     */
     PartitionModel* partitionModelForDevice( const Device* device ) const;
 
     //HACK: all devices change over time, and together make up the state of the CoreModule.
     //      However this makes it hard to show the *original* state of a device.
-    //      With this horrible hack we rescan a single device node to create a Device object
+    //      For each DeviceInfo we keep a second Device object that contains the
-    //      that contains the current state of a disk regardless of subsequent changes.
+    //      current state of a disk regardless of subsequent changes.
-    //      This should probably be redone some other way.
     //              -- Teo 4/2015
     //FIXME: make this horrible method private. -- Teo 12/2015
     Device* immutableDeviceCopy( const Device* device );
 
+    /**
+     * @brief bootLoaderModel returns a model which represents the available boot
+     * loader locations.
+     * The single BootLoaderModel instance belongs to the PCM.
+     * @return the BootLoaderModel.
+     */
     QAbstractItemModel* bootLoaderModel() const;
 
     void createPartitionTable( Device* device, PartitionTable::TableType type );
@@ -96,21 +121,35 @@ public:
 
     void setBootLoaderInstallPath( const QString& path );
 
+    /**
+     * @brief jobs creates and returns a list of jobs which can then apply the changes
+     * requested by the user.
+     * @return a list of jobs.
+     */
     QList< Calamares::job_ptr > jobs() const;
 
     bool hasRootMountPoint() const;
 
     QList< Partition* > efiSystemPartitions() const;
+
+    /**
+     * @brief findPartitionByMountPoint returns a Partition* for a given mount point.
+     * @param mountPoint the mount point to find a partition for.
+     * @return a pointer to a Partition object.
+     * Note that this function looks for partitions in live devices (the "proposed"
+     * state), not the immutable copies. Comparisons with Partition* objects that
+     * refer to immutable Device*s will fail.
+     */
     Partition* findPartitionByMountPoint( const QString& mountPoint ) const;
 
-    void revert();
+    void revert();                      // full revert, thread safe, calls doInit
-    void revertAllDevices();
+    void revertAllDevices();            // convenience function, calls revertDevice
-    void revertDevice( Device* dev );
+    void revertDevice( Device* dev );   // rescans a single Device and updates DeviceInfo
-    void asyncRevertDevice( Device* dev, std::function< void() > callback );
+    void asyncRevertDevice( Device* dev, std::function< void() > callback ); //like revertDevice, but asynchronous
 
-    void clearJobs();
+    void clearJobs();   // only clear jobs, the Device* states are preserved
 
-    bool isDirty();
+    bool isDirty();     // true if there are pending changes, otherwise false
 
     /**
      * To be called when a partition has been altered, but only for changes
@@ -125,9 +164,9 @@ public:
      */
     QList< SummaryInfo > createSummaryInfo() const;
 
-    void dumpQueue() const;
+    void dumpQueue() const; // debug output
 
-    const OsproberEntryList osproberEntries() const;
+    const OsproberEntryList osproberEntries() const;    // os-prober data structure, cached
 
 Q_SIGNALS:
     void hasRootMountPointChanged( bool value );