From a718eb76cb3afce5edc5b1b82e89562d01b30021 Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Tue, 8 Aug 2017 07:54:38 -0400
Subject: [PATCH] Docs: code-documentation about summary page

---
 src/libcalamaresui/viewpages/ViewStep.h | 17 +++++++++++++++--
 src/modules/summary/SummaryPage.cpp     |  3 ++-
 src/modules/summary/SummaryPage.h       | 19 +++++++++++++++++++
 3 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/src/libcalamaresui/viewpages/ViewStep.h b/src/libcalamaresui/viewpages/ViewStep.h
index c68ae31f5..27bab23c8 100644
--- a/src/libcalamaresui/viewpages/ViewStep.h
+++ b/src/libcalamaresui/viewpages/ViewStep.h
@@ -34,6 +34,10 @@ namespace Calamares
  * As of early 2017, a view module can be implemented by deriving from ViewStep
  * in C++ (as a Qt Plugin) or in Python with the PythonQt interface (which also
  * mimics the ViewStep class).
+ *
+ * A ViewStep can describe itself in human-readable format for the SummaryPage
+ * (which shows all of the things which have been collected to be done in the
+ * next exec-step) through prettyStatus() and createSummaryWidget().
  */
 class UIDLLEXPORT ViewStep : public QObject
 {
@@ -43,11 +47,20 @@ public:
     virtual ~ViewStep();
 
     virtual QString prettyName() const = 0;
+
+    /**
+     * Optional. May return a non-empty string describing what this
+     * step is going to do (should be translated). This is also used
+     * in the summary page to describe what is going to be done.
+     * Return an empty string to provide no description.
+     */
     virtual QString prettyStatus() const;
 
     /**
-     * Optional. Should return a widget which will be inserted in the summary
-     * page. The caller takes ownership of the widget.
+     * Optional. May return a widget which will be inserted in the summary
+     * page. The caller takes ownership of the widget. Return nullptr to
+     * provide no widget. In general, this is only used for complicated
+     * steps where prettyStatus() is not sufficient.
      */
     virtual QWidget* createSummaryWidget() const;
 
diff --git a/src/modules/summary/SummaryPage.cpp b/src/modules/summary/SummaryPage.cpp
index 351ef49a4..6d53ba8b6 100644
--- a/src/modules/summary/SummaryPage.cpp
+++ b/src/modules/summary/SummaryPage.cpp
@@ -56,6 +56,8 @@ SummaryPage::SummaryPage( const SummaryViewStep* thisViewStep, QWidget* parent )
 }
 
 
+// Adds a widget for those ViewSteps that want a summary;
+// see SummaryPage documentation and also ViewStep docs.
 void
 SummaryPage::onActivate()
 {
@@ -96,7 +98,6 @@ SummaryPage::onActivate()
     m_layout->addStretch();
 }
 
-
 Calamares::ViewStepList
 SummaryPage::stepsForSummary( const Calamares::ViewStepList& allSteps ) const
 {
diff --git a/src/modules/summary/SummaryPage.h b/src/modules/summary/SummaryPage.h
index 29ec5fcb0..05331d260 100644
--- a/src/modules/summary/SummaryPage.h
+++ b/src/modules/summary/SummaryPage.h
@@ -28,6 +28,25 @@ class QScrollArea;
 class QVBoxLayout;
 class SummaryViewStep;
 
+/** @brief Provide a summary view with to-be-done action descriptions.
+*
+* Those steps that occur since the previous execution step (e.g. that
+* are queued for execution now; in the normal case where there is
+* only one execution step, this means everything that the installer
+* is going to do) are added to the summary view. Each view step
+* can provide one of the following things to display in the summary
+* view:
+*
+* - A string from ViewStep::prettyStatus(), which is formatted
+*   and added as a QLabel to the view. Return an empty string
+*   from prettyStatus() to avoid this.
+* - A QWidget from ViewStep::createSummaryWidget(). This is for
+*   complicated displays not suitable for simple text representation.
+*   Return a nullptr to avoid this.
+*
+* If neither a (non-empty) string nor a widget is returned, the
+* step is not named in the summary.
+*/
 class SummaryPage : public QWidget
 {
     Q_OBJECT