From b4ac6b73c8a188b00868bba4e0497fa2fc47fdfa Mon Sep 17 00:00:00 2001
From: dalto <dalto@fastmail.com>
Date: Sat, 15 Jan 2022 11:13:17 -0600
Subject: [PATCH] [packagechooser,netinstall] Add documentation for
 packagechooser/netinstall integration

---
 src/modules/netinstall/NetInstallPage.cpp      |  2 ++
 src/modules/netinstall/PackageModel.cpp        | 17 ++++++++++++++++-
 src/modules/packagechooser/PackageModel.cpp    |  2 ++
 src/modules/packagechooser/packagechooser.conf | 17 ++++++++++++++++-
 4 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/src/modules/netinstall/NetInstallPage.cpp b/src/modules/netinstall/NetInstallPage.cpp
index 75d7b660c..f897c0018 100644
--- a/src/modules/netinstall/NetInstallPage.cpp
+++ b/src/modules/netinstall/NetInstallPage.cpp
@@ -64,6 +64,7 @@ NetInstallPage::onActivate()
 {
     ui->groupswidget->setFocus();
 
+    // The NetInstallSelect global sotrage value can be used to make additional items selected by default
     Calamares::GlobalStorage* gs = Calamares::JobQueue::instance()->globalStorage();
     if ( gs->contains( "NetinstallSelect" ) && gs->value( "NetinstallSelect" ).canConvert( QVariant::StringList ) )
     {
@@ -72,6 +73,7 @@ NetInstallPage::onActivate()
         static_cast< PackageModel* >( ui->groupswidget->model() )->setSelections( selectNames );
     }
 
+    // If NetInstallAdd is found in global storage, add those items to the tree
     if ( gs->contains( "NetinstallAdd" ) && gs->value( "NetinstallAdd" ).canConvert( QVariant::List ) )
     {
         const QVariantList groups = gs->value( "NetinstallAdd" ).toList();
diff --git a/src/modules/netinstall/PackageModel.cpp b/src/modules/netinstall/PackageModel.cpp
index 015b05303..9eafd898e 100644
--- a/src/modules/netinstall/PackageModel.cpp
+++ b/src/modules/netinstall/PackageModel.cpp
@@ -170,6 +170,15 @@ PackageModel::headerData( int section, Qt::Orientation orientation, int role ) c
     return QVariant();
 }
 
+/** @brief Sets the checked flag on matching groups in the tree
+ *
+ * Recursively traverses the tree pointed to by m_rootItem and
+ * checks if a group name matches any of the items in @p selectNames.
+ * If a match is found, set check the box for that group and it's children.
+ *
+ * Individual packages will not be matched.
+ *
+ */
 void
 PackageModel::setSelections( QStringList selectNames )
 {
@@ -333,7 +342,13 @@ PackageModel::setupModelData( const QVariantList& l )
     emit endResetModel();
 }
 
-
+/** @brief Appends groups to the tree
+ *
+ * Uses the data from @p groupList to add elements to the
+ * existing tree that m_rootItem points to.  If m_rootItem
+ * is not valid, it does nothing
+ *
+ */
 void
 PackageModel::appendModelData( const QVariantList& groupList )
 {
diff --git a/src/modules/packagechooser/PackageModel.cpp b/src/modules/packagechooser/PackageModel.cpp
index f92b6893e..7b7cfc08f 100644
--- a/src/modules/packagechooser/PackageModel.cpp
+++ b/src/modules/packagechooser/PackageModel.cpp
@@ -15,6 +15,8 @@
 
 #include <QFileInfo>
 
+/** @brief A wrapper for CalamaresUtils::getSubMap that excludes the success param
+ */
 static QVariantMap
 getSubMap( const QVariantMap& map, const QString& key )
 {
diff --git a/src/modules/packagechooser/packagechooser.conf b/src/modules/packagechooser/packagechooser.conf
index bb982916e..ca458042b 100644
--- a/src/modules/packagechooser/packagechooser.conf
+++ b/src/modules/packagechooser/packagechooser.conf
@@ -33,6 +33,15 @@ mode: required
 #   in the `exec` section. These package settings will then be handed
 #   off to whatever package manager is configured there.
 #
+# - "netinstall-select"
+#   When this is set, the id(s) selected are passed to the netinstall module.
+#   Any id that matches a group name in that module is set to checked
+#
+# - "netinstall-add"
+#   With this method, the packagechooser module is used to add groups to the
+#   netinstall module.  For this to hav=e any effect.  You must set netinstall,
+#   which is described below.
+#
 # There is no need to put this module in the `exec` section. There
 # are no jobs that this module provides. You should put **other**
 # modules, either *contextualprocess* or *packages* or some custom
@@ -101,13 +110,19 @@ labels:
 #       an additional attempt is made to load the image from the **branding**
 #       directory.
 #
-# The following field is **optional** for an item:
+# The following fields are **optional** for an item:
 #
 #  - *packages* :
 #       List of package names for the product. If using the *method*
 #       "packages", consider this item mandatory (because otherwise
 #       selecting the item would install no packages).
 #
+#  - *netinstall* :
+#       The data in this field should follow the format of a group
+#       from the netinstall module documented in
+#       src/modules/netinstall/netinstall.conf.  This is only used
+#       when method is set to "netinstall-add"
+#
 # # AppData Items #
 #
 # For data provided by AppData XML: the item has an *appdata*