Documentation++

src/calamares/CalamaresApplication.h

@@ -32,6 +32,11 @@ namespace Calamares
 class ModuleManager;
 }
 
+
+/**
+ * @brief The CalamaresApplication class extends QApplication to handle
+ * Calamares startup and lifetime of main components.
+ */
 class CalamaresApplication : public QApplication
 {
     Q_OBJECT
@@ -39,12 +44,27 @@ public:
     CalamaresApplication( int& argc, char* argv[] );
     virtual ~CalamaresApplication();
 
+    /**
+     * @brief init handles the first part of Calamares application startup.
+     * After the main window shows up, the latter part of the startup sequence
+     * (including modules loading) happens asynchronously.
+     */
     void init();
     static CalamaresApplication* instance();
 
+    /**
+     * @brief setDebug controls whether debug mode is enabled
+     */
     void setDebug( bool enabled );
+
+    /**
+     * @brief isDebug returns true if running in debug mode, otherwise false.
+     */
     bool isDebug();
 
+    /**
+     * @brief mainWindow returns the Calamares application main window.
+     */
     CalamaresWindow* mainWindow();
 
 private slots:

src/calamares/CalamaresWindow.h

@@ -27,6 +27,9 @@ namespace Calamares
 class DebugWindow;
 }
 
+/**
+ * @brief The CalamaresWindow class represents the main window of the Calamares UI.
+ */
 class CalamaresWindow : public QWidget
 {
     Q_OBJECT

src/calamares/progresstree/ProgressTreeDelegate.h

@@ -21,6 +21,12 @@
 
 #include <QStyledItemDelegate>
 
+
+/**
+ * @brief The ProgressTreeDelegate class customizes the look and feel of the
+ * ProgressTreeView elements.
+ * @see ProgressTreeView
+ */
 class ProgressTreeDelegate : public QStyledItemDelegate
 {
     Q_OBJECT

src/calamares/progresstree/ProgressTreeItem.h

@@ -22,6 +22,12 @@
 #include <QList>
 #include <QVariant>
 
+
+/**
+ * @brief The ProgressTreeItem class represents an item in the
+ * ProgressTreeModel/ProgressTreeView.
+ * Each item generally represents a ViewStep.
+ */
 class ProgressTreeItem
 {
 public:

src/calamares/progresstree/ProgressTreeModel.h

@@ -24,6 +24,10 @@
 class ProgressTreeRoot;
 class ProgressTreeItem;
 
+
+/**
+ * @brief The ProgressTreeModel class implements a model for the ProgressTreeView.
+ */
 class ProgressTreeModel : public QAbstractItemModel
 {
     Q_OBJECT

src/calamares/progresstree/ProgressTreeView.h

@@ -23,6 +23,11 @@
 
 class ProgressTreeDelegate;
 
+/**
+ * @brief The ProgressTreeView class is a modified QTreeView which displays the
+ * available view steps and the user's progress through them.
+ * @note singleton, only access through ProgressTreeView::instance().
+ */
 class ProgressTreeView : public QTreeView
 {
     Q_OBJECT
@@ -32,6 +37,9 @@ public:
     explicit ProgressTreeView( QWidget* parent = 0 );
     virtual ~ProgressTreeView();
 
+    /**
+     * @brief setModel assigns a model to this view.
+     */
     void setModel( QAbstractItemModel* model ) override;
 
 private:

src/libcalamaresui/ViewManager.h

@@ -33,28 +33,82 @@ namespace Calamares
 class ViewStep;
 class ExecutionViewStep;
 
+/**
+ * @brief The ViewManager class handles progression through view pages.
+ * @note Singleton object, only use through ViewManager::instance().
+ */
 class UIDLLEXPORT ViewManager : public QObject
 {
     Q_OBJECT
 public:
+    /**
+     * @brief instance access to the ViewManager singleton.
+     * @return
+     */
     static ViewManager* instance();
 
     explicit ViewManager( QObject* parent = nullptr );
     virtual ~ViewManager();
 
+    /**
+     * @brief centralWidget always returns the central widget in the Calamares main
+     * window.
+     * @return a pointer to the active QWidget (usually a wizard page provided by a
+     * view module).
+     */
     QWidget* centralWidget();
 
+    /**
+     * @brief addViewStep appends a view step to the roster.
+     * @param step a pointer to the ViewStep object to add.
+     * @note a ViewStep is the active instance of a view module, it aggregates one
+     * or more view pages, plus zero or more jobs which may be created at runtime.
+     */
     void addViewStep( ViewStep* step );
 
+    /**
+     * @brief viewSteps returns the list of currently present view steps.
+     * @return the ViewStepList.
+     * This should only return an empty list before startup is complete.
+     */
     ViewStepList viewSteps() const;
+
+    /**
+     * @brief currentStep returns the currently active ViewStep, i.e. the ViewStep
+     * which owns the currently visible view page.
+     * @return the active ViewStep. Do not confuse this with centralWidget().
+     * @see ViewStep::centralWidget
+     */
     ViewStep* currentStep() const;
+
+    /**
+     * @brief currentStepIndex returns the index of the currently active ViewStep.
+     * @return the index.
+     */
     int currentStepIndex() const;
 
 
 public slots:
+    /**
+     * @brief next moves forward to the next page of the current ViewStep (if any),
+     * or to the first page of the next ViewStep if the current ViewStep doesn't
+     * have any more pages.
+     */
     void next();
+
+    /**
+     * @brief back moves backward to the previous page of the current ViewStep (if any),
+     * or to the last page of the previous ViewStep if the current ViewStep doesn't
+     * have any pages before the current one.
+     */
     void back();
 
+    /**
+     * @brief onInstallationFailed displays an error message when a fatal failure
+     * happens in a ViewStep.
+     * @param message the error string.
+     * @param details the details string.
+     */
     void onInstallationFailed( const QString& message, const QString& details );
 
 signals:

src/libcalamaresui/modulesystem/Module.h

@@ -37,15 +37,32 @@ void operator>>( const QVariantMap& moduleDescriptor, Calamares::Module* m );
 namespace Calamares
 {
 
+/**
+ * @brief The Module class is a common supertype for Calamares modules.
+ * It enforces a common interface for all the different types of modules, and it
+ * takes care of creating an object of the correct type starting from a module
+ * descriptor structure.
+ */
 class UIDLLEXPORT Module
 {
 public:
+    /**
+     * @brief The Type enum represents the intended functionality of the module
+     * Every module is either a job module or a view module.
+     * A job module is a single Calamares job.
+     * A view module has a UI (one or more view pages) and zero-to-many jobs.
+     */
     enum Type
     {
         Job,
         View
     };
 
+    /**
+     * @brief The Interface enum represents the interface through which the module
+     * talks to Calamares.
+     * Not all Type-Interface associations are valid.
+     */
     enum Interface
     {
         QtPluginInterface,
@@ -55,27 +72,100 @@ public:
     };
     virtual ~Module();
 
+    /**
+     * @brief fromDescriptor creates a new Module object of the correct type.
+     * @param moduleDescriptor a module descriptor, already parsed into a variant map.
+     * @param instanceId the instance id of the new module instance.
+     * @param configFileName the name of the configuration file to read.
+     * @param moduleDirectory the path to the directory with this module's files.
+     * @return a pointer to an object of a subtype of Module.
+     */
     static Module* fromDescriptor( const QVariantMap& moduleDescriptor,
                                    const QString& instanceId,
                                    const QString& configFileName,
                                    const QString& moduleDirectory );
 
+    /**
+     * @brief name returns the name of this module.
+     * @return a string with this module's name.
+     */
     virtual QString name() const final;
+
+    /**
+     * @brief instanceId returns the instance id of this module.
+     * @return a string with this module's instance id.
+     */
     virtual QString instanceId() const final;
+
+    /**
+     * @brief instanceKey returns the instance key of this module.
+     * @return a string with the instance key.
+     * A module instance's instance key is modulename@instanceid.
+     * @example "partition@partition" (default configuration) or
+     * "locale@someconfig" (custom configuration)
+     */
     virtual QString instanceKey() const final;
+
+    /**
+     * @brief requiredModules a list of names of modules required by this one.
+     * @return the list of names.
+     * The module dependencies system is currently incomplete and unused.
+     */
     virtual QStringList requiredModules() const;
+
+    /**
+     * @brief location returns the full path of this module's directory.
+     * @return the path.
+     */
     virtual QString location() const final;
+
+    /**
+     * @brief type returns the Type of this module object.
+     * @return the type enum value.
+     */
     virtual Type type() const = 0;
+
+    /**
+     * @brief typeString returns a user-visible string for the module's type.
+     * @return the type string.
+     */
     virtual QString typeString() const;
+
+    /**
+     * @brief interface the Interface used by this module.
+     * @return the interface enum value.
+     */
     virtual Interface interface() const = 0;
+
+    /**
+     * @brief interface returns a user-visible string for the module's interface.
+     * @return the interface string.
+     */
     virtual QString interfaceString() const;
 
+    /**
+     * @brief isLoaded reports on the loaded status of a module.
+     * @return true if the module's loading phase has finished, otherwise false.
+     */
     virtual bool isLoaded() const;
 
+    /**
+     * @brief loadSelf initialized the module.
+     * Subclasses must reimplement this depending on the module type and interface.
+     */
     virtual void loadSelf() = 0;
 
+    /**
+     * @brief jobs returns any jobs exposed by this module.
+     * @return a list of jobs (can be empty).
+     */
     virtual QList< job_ptr > jobs() const = 0;
 
+    /**
+     * @brief configurationMap returns the contents of the configuration file for
+     * this module instance.
+     * @return the instance's configuration, already parsed from YAML into a variant map.
+     */
     QVariantMap configurationMap();
 
 protected:

src/libcalamaresui/modulesystem/ModuleManager.h

@@ -30,6 +30,13 @@ namespace Calamares
 
 class Module;
 
+/**
+ * @brief The ModuleManager class is a singleton which manages Calamares modules.
+ *
+ * It goes through the module search directories and reads module metadata. It then
+ * constructs objects of type Module, loads them and makes them accessible by their
+ * instance key.
+ */
 class ModuleManager : public QObject
 {
     Q_OBJECT
@@ -46,11 +53,31 @@ public:
      */
     void init();
 
+    /**
+     * @brief loadedInstanceKeys returns a list of instance keys for the available
+     * modules.
+     * @return a QStringList with the instance keys.
+     */
     QStringList loadedInstanceKeys();
+
+    /**
+     * @brief moduleDescriptor returns the module descriptor structure for a given module.
+     * @param name the name of the module for which to return the module descriptor.
+     * @return the module descriptor, as a variant map already parsed from YAML.
+     */
     QVariantMap moduleDescriptor( const QString& name );
 
+    /**
+     * @brief moduleInstance returns a Module object for a given instance key.
+     * @param instanceKey the instance key for a module instance.
+     * @return a pointer to an object of a subtype of Module.
+     */
     Module* moduleInstance( const QString& instanceKey );
 
+    /**
+     * @brief loadModules initiates the asynchronous module loading operation.
+     * When this is done, the signal modulesLoaded is emitted.
+     */
     void loadModules();
 
 signals: