Docs: code-documentation about summary page

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
+     * Optional. May return a widget which will be inserted in the summary
-     * page. The caller takes ownership of the widget.
+     * 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;
 

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
 {

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