From d33752c66ce5de240884b926b68368aa97d9669a Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Fri, 15 Feb 2019 20:53:55 +0100
Subject: [PATCH] [libcalamaresui] Refactor Requirements classes

 - improve naming of member variables
 - expand documentation
---
 .../modulesystem/ModuleManager.cpp            |  4 +--
 src/libcalamaresui/modulesystem/Requirement.h | 32 ++++++++++++-------
 src/modules/welcome/checker/CheckerWidget.cpp |  8 ++---
 3 files changed, 26 insertions(+), 18 deletions(-)

diff --git a/src/libcalamaresui/modulesystem/ModuleManager.cpp b/src/libcalamaresui/modulesystem/ModuleManager.cpp
index 722aa7296..ef618de86 100644
--- a/src/libcalamaresui/modulesystem/ModuleManager.cpp
+++ b/src/libcalamaresui/modulesystem/ModuleManager.cpp
@@ -317,7 +317,7 @@ ModuleManager::checkRequirements()
 
         for (const auto& module : m_loadedModulesByInstanceKey )
         {
-            auto l = module->checkRequirements();
+            RequirementsList l = module->checkRequirements();
             if ( l.length() > 0 )
             {
                 cDebug() << "  .." << module->name() << l.length() << "requirements";
@@ -325,7 +325,7 @@ ModuleManager::checkRequirements()
             }
             for (const auto& r : l)
             {
-                if (r.required && !r.checked)
+                if ( r.mandatory && !r.satisfied )
                     acceptable = false;
             }
         }
diff --git a/src/libcalamaresui/modulesystem/Requirement.h b/src/libcalamaresui/modulesystem/Requirement.h
index a90d5775b..69e170c94 100644
--- a/src/libcalamaresui/modulesystem/Requirement.h
+++ b/src/libcalamaresui/modulesystem/Requirement.h
@@ -28,22 +28,30 @@ namespace Calamares
 
 /**
  * An indication of a requirement, which is checked in preparation
- * for system installation. An entry has a name and some explanation,
- * as well as three meaningful states:
- *  - checked = true, the requirement is met (green)
- *  - checked = false, the requirement is not met
- *      - required = false, warn about it (yellow), no failure
- *      - required = true, prohibit installation (red)
+ * for system installation. An entry has a name and some explanation functions
+ * (functions, because they need to respond to translations).
+ *
+ * A requirement can be *satisfied* or not.
+ * A requirement can be optional (i.e. a "good to have") or mandatory.
+ *
+ * Requirements which are not satisfied, and also mandatory, will prevent the
+ * installation from proceeding.
  */
 struct RequirementEntry
 {
+    using TextFunction = std::function< QString() >;
+
+    /// @brief name of this requirement; not shown to user and used as ID
     QString name;
-    std::function< QString() > enumerationText; //Partial string, inserted in a
-                                                //list of requirements to satisfy.
-    std::function< QString() > negatedText;     //Complete sentence about this requirement
-                                                //not having been met.
-    bool checked;
-    bool required;
+
+    /// @brief Description of this requirement, for use in user-visible lists
+    TextFunction enumerationText;
+
+    /// @brief User-visible string to show that the requirement is not met
+    std::function< QString() > negatedText;
+
+    bool satisfied;
+    bool mandatory;
 };
 
 using RequirementsList = QList< RequirementEntry >;
diff --git a/src/modules/welcome/checker/CheckerWidget.cpp b/src/modules/welcome/checker/CheckerWidget.cpp
index 2f1d7b909..2ad79abfd 100644
--- a/src/modules/welcome/checker/CheckerWidget.cpp
+++ b/src/modules/welcome/checker/CheckerWidget.cpp
@@ -60,15 +60,15 @@ CheckerWidget::init( const Calamares::RequirementsList& checkEntries )
 
     for ( const auto& entry : checkEntries )
     {
-        if ( !entry.checked )
+        if ( !entry.satisfied )
         {
-            CheckItemWidget* ciw = new CheckItemWidget( entry.checked, entry.required );
+            CheckItemWidget* ciw = new CheckItemWidget( entry.satisfied, entry.mandatory );
             CALAMARES_RETRANSLATE( ciw->setText( entry.negatedText() ); )
             m_entriesLayout->addWidget( ciw );
             ciw->setSizePolicy( QSizePolicy::Expanding, QSizePolicy::Preferred );
 
             allChecked = false;
-            if ( entry.required )
+            if ( entry.mandatory )
             {
                 requirementsSatisfied = false;
             }
@@ -182,7 +182,7 @@ CheckerWidget::showDetailsDialog( const Calamares::RequirementsList& checkEntrie
         if ( entry.enumerationText().isEmpty() )
             continue;
 
-        CheckItemWidget* ciw = new CheckItemWidget( entry.checked, entry.required );
+        CheckItemWidget* ciw = new CheckItemWidget( entry.satisfied, entry.mandatory );
         CALAMARES_RETRANSLATE( ciw->setText( entry.enumerationText() ); )
         entriesLayout->addWidget( ciw );
         ciw->setSizePolicy( QSizePolicy::Expanding, QSizePolicy::Preferred );