Add API documentation

src/lib/stackedwidgets.cpp

 /*
  *  stackedwidgets.cpp  -  classes implementing stacked widgets
  *  Program:  kalarm
- *  SPDX-FileCopyrightText: 2008-2021 David Jarvie <djarvie@kde.org>
+ *  SPDX-FileCopyrightText: 2008-2022 David Jarvie <djarvie@kde.org>
  *
  *  SPDX-License-Identifier: GPL-2.0-or-later
  */
@@ -44,17 +44,17 @@ StackedScrollWidget::StackedScrollWidget(StackedScrollGroup* group, QWidget* par
     setSizePolicy(QSizePolicy::MinimumExpanding, QSizePolicy::MinimumExpanding);
 }
 
-StackedScrollGroup::StackedScrollGroup(QDialog* dlg, QObject* tabParent)
-    : StackedGroupT<QScrollArea>(tabParent)
+StackedScrollGroup::StackedScrollGroup(QDialog* dlg, QWidget* container)
+    : StackedGroupT<QScrollArea>(container)
     , mDialog(dlg)
 {
 }
 
 /******************************************************************************
-* Return the minimum size for the tab, adjusted if necessary to a height that
-* fits the screen.
-* In order to make the QStackedWidget containing the tabs take the correct
-* size, the value returned is actually the minimum size of the largest tab.
+* Return the minimum size for the tabs, constrained if necessary to a height
+* that fits the screen.
+* In order to make the widget containing the tabs take the correct size, the
+* value returned is actually the minimum size of the largest tab.
 * Otherwise, only the currently visible tab would be taken into account with
 * the result that the dialog would initially be displayed too small.
 */

src/lib/stackedwidgets.h

 /*
  *  stackedwidgets.h  -  classes implementing stacked widgets
  *  Program:  kalarm
- *  SPDX-FileCopyrightText: 2008-2021 David Jarvie <djarvie@kde.org>
+ *  SPDX-FileCopyrightText: 2008-2022 David Jarvie <djarvie@kde.org>
  *
  *  SPDX-License-Identifier: GPL-2.0-or-later
  */
@@ -36,6 +36,11 @@ template <class T> class StackedGroupT;
  *  A widget contained in a stack, whose minimum size hint is that of the largest
  *  widget in the stack. This class works together with StackedGroup.
  *
+ *  Do not use this class for widgets contained in a QStackedWidget or
+ *  StackedWidget.
+ *
+ *  @tparam T  The base class for this widget. Must be derived from QWidget.
+
  *  @author David Jarvie <djarvie@kde.org>
  */
 template <class T>
@@ -43,8 +48,8 @@ class StackedGroupWidgetT : public T
 {
 public:
     /** Constructor.
+     *  @param group  The stack group to insert this widget into.
      *  @param parent The parent object of this widget.
-     *  @param group The stack group to insert this widget into.
      */
     explicit StackedGroupWidgetT(StackedGroupT<T>* group, QWidget* parent = nullptr)
           : T(parent),
@@ -62,7 +67,8 @@ private:
 
 /**
  *  A group of stacked widgets whose minimum size hints are all equal to the
- *  largest widget's minimum size hint.
+ *  largest widget's minimum size hint. Use this alongside the widgets' container,
+ *  e.g. QTabWidget.
  *
  *  It is inherited from QObject solely to ensure automatic deletion when its
  *  parent widget is deleted.
@@ -73,7 +79,13 @@ template <class T>
 class StackedGroupT : public QObject
 {
 public:
-    explicit StackedGroupT(QObject* parent = nullptr) : QObject(parent) {}
+    /** Constructor.
+     *  @param container  The parent widget. This should be set to the container
+     *                    for the stacked widgets, which will ensure that this
+     *                    object is deleted when the container is deleted.
+     */
+    explicit StackedGroupT(QWidget* container) : QObject(container) {}
+
     void  addWidget(StackedGroupWidgetT<T>* w)     { mWidgets += w; }
     void  removeWidget(StackedGroupWidgetT<T>* w)  { mWidgets.removeAll(w); }
     virtual QSize minimumSizeHint() const;
@@ -91,17 +103,20 @@ QSize StackedGroupT<T>::minimumSizeHint() const
     return sz;
 }
 
-/** A non-scrollable stacked widget. */
+/** A non-scrollable stacked QWidget. */
 using StackedGroupWidget = StackedGroupWidgetT<QWidget>;
-/** A group of non-scrollable stacked widgets. */
+/** A group of non-scrollable stacked widgets which are each derived from QWidget. */
 using StackedGroup = StackedGroupT<QWidget>;
 
 
 class StackedScrollGroup;
 
 /**
- *  A stacked widget which becomes scrollable when necessary to fit the height
- *  of the screen.
+ *  A stacked QScrollArea widget, which becomes scrollable when necessary to
+ *  fit the height of the screen.
+ *
+ *  Do not use this class for widgets contained in a QStackedWidget or
+ *  StackedWidget.
  *
  *  @author David Jarvie <djarvie@kde.org>
  */
@@ -113,20 +128,48 @@ public:
 };
 
 /**
- *  A group of stacked widgets which individually become scrollable when necessary
- *  to fit the height of the screen.
+ *  A group of stacked StackedScrollWidget widgets, which individually become
+ *  scrollable when necessary to fit the height of the screen.
  *
  *  @author David Jarvie <djarvie@kde.org>
  */
 class StackedScrollGroup : public StackedGroupT<QScrollArea>
 {
 public:
-    StackedScrollGroup(QDialog*, QObject* tabParent);
-    QSize    minimumSizeHint() const override;
-    int      heightReduction() const { return mHeightReduction; }
-    QSize    adjustSize(bool force = false);
-    void     setSized()              { mSized = true; }
-    bool     sized() const           { return mSized; }
+    /** Constructor.
+     *  @param dialog     The dialog which contains the widgets.
+     *  @param container  The parent widget. This should be set to the container
+     *                    for the stacked widgets, which will ensure that this
+     *                    object is deleted when the container is deleted.
+     */
+    StackedScrollGroup(QDialog* dialog, QWidget* container);
+
+    /** Return the minimum size for the tabs, constrained if necessary to a height
+     *  that fits the dialog into the screen. The dialog height must have been
+     *  previously evaluated by calling adjustSize().
+     */
+    QSize minimumSizeHint() const override;
+
+    /** Return the reduction in dialog height which adjustSize() performed in
+     *  order to fit the dialog to the desktop.
+     */
+    int heightReduction() const  { return mHeightReduction; }
+
+    /** Set the minimum height for the dialog, so as to accommodate the tabs,
+     *  but constrained to fit the desktop. If necessary, the tab contents are
+     *  made scrollable.
+     *  @param force  If false, this method will only evaluate and set the
+     *                minimum dialog height the first time it is called. Set
+     *                true to force re-evaluation.
+     *  @return The minimum size for the dialog, or null if the size was not evaluated.
+     */
+    QSize adjustSize(bool force = false);
+
+    /** Prevent adjustSize(false) from evaluating or setting the dialog height. */
+    void setSized()              { mSized = true; }
+
+    /** Return whether the dialog size has already been set, e.g. by adjustSize(). */
+    bool sized() const           { return mSized; }
 
 private:
     QSize    maxMinimumSizeHint() const;