From 99a1c2245f7b86bf8fc765c01d072b791801bc99 Mon Sep 17 00:00:00 2001 From: Teo Mrnjavac Date: Tue, 28 Feb 2017 18:08:02 +0100 Subject: [PATCH] Documentation++ --- src/calamares/CalamaresApplication.h | 20 +++++ src/calamares/CalamaresWindow.h | 3 + .../progresstree/ProgressTreeDelegate.h | 6 ++ src/calamares/progresstree/ProgressTreeItem.h | 6 ++ .../progresstree/ProgressTreeModel.h | 4 + src/calamares/progresstree/ProgressTreeView.h | 8 ++ src/libcalamaresui/ViewManager.h | 54 +++++++++++ src/libcalamaresui/modulesystem/Module.h | 90 +++++++++++++++++++ .../modulesystem/ModuleManager.h | 27 ++++++ 9 files changed, 218 insertions(+) diff --git a/src/calamares/CalamaresApplication.h b/src/calamares/CalamaresApplication.h index 5aa33ed97..2c1cd1a09 100644 --- a/src/calamares/CalamaresApplication.h +++ b/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: diff --git a/src/calamares/CalamaresWindow.h b/src/calamares/CalamaresWindow.h index 6ea9602a5..7b2cfa6fa 100644 --- a/src/calamares/CalamaresWindow.h +++ b/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 diff --git a/src/calamares/progresstree/ProgressTreeDelegate.h b/src/calamares/progresstree/ProgressTreeDelegate.h index b3f6d4ab2..ed3aae9de 100644 --- a/src/calamares/progresstree/ProgressTreeDelegate.h +++ b/src/calamares/progresstree/ProgressTreeDelegate.h @@ -21,6 +21,12 @@ #include + +/** + * @brief The ProgressTreeDelegate class customizes the look and feel of the + * ProgressTreeView elements. + * @see ProgressTreeView + */ class ProgressTreeDelegate : public QStyledItemDelegate { Q_OBJECT diff --git a/src/calamares/progresstree/ProgressTreeItem.h b/src/calamares/progresstree/ProgressTreeItem.h index 66c07863a..bfce062a7 100644 --- a/src/calamares/progresstree/ProgressTreeItem.h +++ b/src/calamares/progresstree/ProgressTreeItem.h @@ -22,6 +22,12 @@ #include #include + +/** + * @brief The ProgressTreeItem class represents an item in the + * ProgressTreeModel/ProgressTreeView. + * Each item generally represents a ViewStep. + */ class ProgressTreeItem { public: diff --git a/src/calamares/progresstree/ProgressTreeModel.h b/src/calamares/progresstree/ProgressTreeModel.h index 39ec64a3e..60db77939 100644 --- a/src/calamares/progresstree/ProgressTreeModel.h +++ b/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 diff --git a/src/calamares/progresstree/ProgressTreeView.h b/src/calamares/progresstree/ProgressTreeView.h index b908449c2..fae75d0dc 100644 --- a/src/calamares/progresstree/ProgressTreeView.h +++ b/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: diff --git a/src/libcalamaresui/ViewManager.h b/src/libcalamaresui/ViewManager.h index 01599d6a7..6e694a14a 100644 --- a/src/libcalamaresui/ViewManager.h +++ b/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: diff --git a/src/libcalamaresui/modulesystem/Module.h b/src/libcalamaresui/modulesystem/Module.h index 6934a554e..7c331351d 100644 --- a/src/libcalamaresui/modulesystem/Module.h +++ b/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: diff --git a/src/libcalamaresui/modulesystem/ModuleManager.h b/src/libcalamaresui/modulesystem/ModuleManager.h index 7aa3ca418..05ad15178 100644 --- a/src/libcalamaresui/modulesystem/ModuleManager.h +++ b/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: