Utils: Add some documentation for LayoutBuilder and BaseAspect

... and some related classes and an enum.

This is not a complete documentation for all aspect classes.

Change-Id: I2d98aec012394cc4016e571884b861db7a498b1b
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

src/libs/utils/layoutbuilder.cpp

@@ -35,6 +35,89 @@
 
 namespace Utils {
 
+/*!
+    \enum Utils::LayoutBuilder::LayoutType
+    \inmodule QtCreator
+
+    The LayoutType enum describes the type of \c QLayout a layout builder
+    operates on.
+
+    \value FormLayout
+    \value GridLayout
+*/
+
+/*!
+    \class Utils::LayoutBuilder::LayoutItem
+    \inmodule QtCreator
+
+    \brief The LayoutItem class represents widgets, layouts, and aggregate
+    items for use in conjunction with layout builders.
+
+    Layout items are typically implicitly constructed when adding items to a
+    \c LayoutBuilder instance using \c LayoutBuilder::addItem() or
+    \c LayoutBuilder::addItems() and never stored in user code.
+*/
+
+/*!
+    Constructs a layout item instance representing an empty cell.
+ */
+LayoutBuilder::LayoutItem::LayoutItem()
+{}
+
+
+/*!
+    Constructs a layout item proxy for \a layout, spanning the number
+    of cells specified by \a span in the target layout, with alignment \a align.
+ */
+LayoutBuilder::LayoutItem::LayoutItem(QLayout *layout, int span, Qt::Alignment align)
+    : layout(layout), span(span), align(align)
+{}
+
+/*!
+    Constructs a layout item proxy for \a widget, spanning the number
+    of cell specified by \a span in the target layout, with alignment \a align.
+ */
+LayoutBuilder::LayoutItem::LayoutItem(QWidget *widget, int span, Qt::Alignment align)
+    : widget(widget), span(span), align(align)
+{}
+
+/*!
+    Constructs a layout item representing a \c BaseAspect.
+
+    This ultimately uses the \a aspect's \c addToLayout(LayoutBuilder &) function,
+    which in turn can add one or more layout items to the target layout.
+
+    \sa BaseAspect::addToLayout()
+ */
+LayoutBuilder::LayoutItem::LayoutItem(BaseAspect *aspect)
+    : aspect(aspect)
+{}
+
+/*!
+    Constructs a layout item containing some static \a text.
+ */
+LayoutBuilder::LayoutItem::LayoutItem(const QString &text) : text(text) {}
+
+/*!
+    \class Utils::LayoutBuilder
+    \inmodule QtCreator
+
+    \brief The LayoutBuilder class provides a convenient way to fill \c QFormLayout
+    and \c QGridLayouts with contents.
+
+    Filling a layout with items happens item-by-item, row-by-row.
+
+    A LayoutBuilder instance is typically used locally within a function and never stored.
+
+    \sa addItem(), addItems(), addRow(), finishRow()
+*/
+
+
+/*!
+    Constructs a new layout builder with the specified \a layoutType.
+
+    The constructed layout will be attached to the provided \c QWidget \a parent.
+ */
 LayoutBuilder::LayoutBuilder(QWidget *parent, LayoutType layoutType)
 {
     if (layoutType == FormLayout) {
@@ -47,6 +130,13 @@ LayoutBuilder::LayoutBuilder(QWidget *parent, LayoutType layoutType)
     }
 }
 
+/*!
+    Constructs a new layout builder to extend an existing \a layout.
+
+    This constructor can be used to continue the work of previous layout building.
+    The type of the underlying layout and previous contents will be retained,
+    new items will be added below existing ones.
+ */
 LayoutBuilder::LayoutBuilder(QLayout *layout)
 {
     if (auto fl = qobject_cast<QFormLayout *>(layout)) {
@@ -58,12 +148,19 @@ LayoutBuilder::LayoutBuilder(QLayout *layout)
     }
 }
 
+/*!
+    Destructs a layout builder.
+ */
 LayoutBuilder::~LayoutBuilder()
 {
     if (m_formLayout)
         flushPendingFormItems();
 }
 
+/*!
+    Instructs a layout builder to finish the current row.
+    This is implicitly called by LayoutBuilder's destructor.
+ */
 LayoutBuilder &LayoutBuilder::finishRow()
 {
     if (m_formLayout)
@@ -77,16 +174,31 @@ LayoutBuilder &LayoutBuilder::finishRow()
     return *this;
 }
 
+/*!
+    This starts a new row containing the \a item. The row can be further extended by
+    other items using \c addItem() or \c addItems().
+
+    \sa finishRow(), addItem(), addItems()
+ */
 LayoutBuilder &LayoutBuilder::addRow(const LayoutItem &item)
 {
     return finishRow().addItem(item);
 }
 
+/*!
+    This starts a new row containing \a items. The row can be further extended by
+    other items using \c addItem() or \c addItems().
+
+    \sa finishRow(), addItem(), addItems()
+ */
 LayoutBuilder &LayoutBuilder::addRow(const QList<LayoutBuilder::LayoutItem> &items)
 {
     return finishRow().addItems(items);
 }
 
+/*!
+    \internal
+ */
 void LayoutBuilder::flushPendingFormItems()
 {
     QTC_ASSERT(m_formLayout, return);
@@ -135,6 +247,9 @@ void LayoutBuilder::flushPendingFormItems()
     m_pendingFormItems.clear();
 }
 
+/*!
+    Returns the layout this layout builder operates on.
+ */
 QLayout *LayoutBuilder::layout() const
 {
     if (m_formLayout)
@@ -142,6 +257,9 @@ QLayout *LayoutBuilder::layout() const
     return m_gridLayout;
 }
 
+/*!
+    Adds the layout item \a item to the current row.
+ */
 LayoutBuilder &LayoutBuilder::addItem(const LayoutItem &item)
 {
     if (item.widget && !item.widget->parent())
@@ -161,6 +279,9 @@ LayoutBuilder &LayoutBuilder::addItem(const LayoutItem &item)
     return *this;
 }
 
+/*!
+    Adds the layout item \a items to the current row.
+ */
 LayoutBuilder &LayoutBuilder::addItems(const QList<LayoutBuilder::LayoutItem> &items)
 {
     for (const LayoutItem &item : items)