Several improvements to documentation

* List all applicable attached properties for each layout
* Move the stuff that describes min,pref and max sizes from GridLayout
  to the Layout docs.
* Document that all layouts \inherits Item. (Even if they don't directly
  inherit, this is consistent with how the positioners are documented)
* Add some links to Row, Column and Grid where appropriate
* Use \qmlattachedproperty instead of \qmlproperty for the attached
  properties. (Again, consistent with how the Positioners attached
  properties are documented)
* Change POSITIVE_INFINITE to the correct POSITIVE_INFINITY

Change-Id: Ia9272faa479b48a97300b031402c0380ca113d7b
Reviewed-by: Caroline Chao <caroline.chao@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

3 files changed, 96 insertions, 44 deletions

diff --git a/src/layouts/doc/src/qtquicklayouts-index.qdoc b/src/layouts/doc/src/qtquicklayouts-index.qdoc
index fdc1c70a..c2280f5d 100644
--- a/src/layouts/doc/src/qtquicklayouts-index.qdoc
+++ b/src/layouts/doc/src/qtquicklayouts-index.qdoc
@@ -29,7 +29,14 @@
     \page qtquicklayouts-index.html
     \title Qt Quick Layouts
 
-    \brief A module with a set of QML elements that arranges QML items in an user interface.
+    \brief A module with a set of QML elements that arrange QML items in a user interface.
+
+    Qt Quick Layouts are a set of QML types used to arrange items in a user interface. In contrast
+    to \l{Item Positioners}{positioners}, Qt Quick Layouts can also resize their items. This makes
+    them well suited for resizable user interfaces. Since layouts are items they can consequently
+    be nested.
+
+    The module is new in Qt 5.1 and requires \l{Qt Quick} 2.1.
 
     \section1 Getting started
 
@@ -40,9 +47,6 @@
     \endcode
 
     \section1 Layouts
-    Layouts are items that are used to arrange items in the user interface. The layout is dynamic -
-    when the layout changes geometry it will typically influence the arrangement of its child
-    items. Since a layout is an item, layouts can consequently be nested.
 
     \annotatedlist layouts
 
diff --git a/src/layouts/qquicklayout.cpp b/src/layouts/qquicklayout.cpp
index 48b80255..86eac072 100644
--- a/src/layouts/qquicklayout.cpp
+++ b/src/layouts/qquicklayout.cpp
@@ -60,11 +60,33 @@
     For instance, you can specify \l minimumWidth, \l preferredWidth, and
     \l maximumWidth if the default values are not satisfactory.
 
-    \l fillWidth and \l fillHeight allows you to specify whether an item should
-    fill the cell(s) it occupies. This allows it to stretch between \l minimumWidth
-    and \l maximumWidth (or \l minimumHeight and \l maximumHeight if \l fillHeight is \c true).
+    When a layout is resized, items may grow or shrink. Due to this, items have a
+    \l{Layout::minimumWidth}{minimum size}, \l{Layout::preferredWidth}{preferred size} and a
+    \l{Layout::maximumWidth}{maximum size}.
+
+    For each item, preferred size may come from one of several sources. It can be specified with
+    the \l preferredWidth and \l preferredHeight properties. If these properties are not
+    specified, it will use the item's \l{Item::implicitWidth}{implicitWidth} or
+    \l{Item::implicitHeight}{implicitHeight} as the preferred size.
+    Finally, if neither of these properties are set, it will use the \l{Item::width}{width} and
+    \l{Item::height}{height} properties of the item. Note that is provided only as a final
+    fallback. If you want to override the preferred size, you should use
+    \l preferredWidth or \l preferredHeight.
+
+    If minimum size have not been explicitly specified on an item, the size is set to \c 0.
+    If maximum size have not been explicitly specified on an item, the size is set to
+    \c Number.POSITIVE_INFINITY.
+
+    For layouts, the implicit minimum and maximum size depends on the content of the layouts.
+
+    The \l fillWidth and \l fillHeight properties can either be \c true or \c false. If it is \c
+    false, the item's size will be fixed to its preferred size. Otherwise, it will grow or shrink
+    between its minimum and maximum size as the layout is resized.
+
+    \note It is not recommended to have bindings to the x, y, width, or height properties of items
+    in a layout, since this would conflict with the goal of the Layout, and also cause binding
+    loops.
 
-    If \l fillWidth or \l fillHeight is \c false, the items' size will be fixed to its preferred size.
 
     \sa GridLayout
     \sa RowLayout
@@ -100,7 +122,7 @@ QQuickLayoutAttached::QQuickLayoutAttached(QObject *parent)
 }
 
 /*!
-    \qmlproperty real Layout::minimumWidth
+    \qmlattachedproperty real Layout::minimumWidth
 
     This property holds the maximum width of an item in a layout.
     The default value is the items implicit minimum width.
@@ -129,7 +151,7 @@ void QQuickLayoutAttached::setMinimumWidth(qreal width)
 }
 
 /*!
-    \qmlproperty real Layout::minimumHeight
+    \qmlattachedproperty real Layout::minimumHeight
 
     The default value is the items implicit minimum height.
 
@@ -156,7 +178,7 @@ void QQuickLayoutAttached::setMinimumHeight(qreal height)
 }
 
 /*!
-    \qmlproperty real Layout::preferredWidth
+    \qmlattachedproperty real Layout::preferredWidth
 
     This property holds the preferred width of an item in a layout.
     If the preferred width is -1 it will be ignored, and the layout
@@ -177,7 +199,7 @@ void QQuickLayoutAttached::setPreferredWidth(qreal width)
 }
 
 /*!
-    \qmlproperty real Layout::preferredHeight
+    \qmlattachedproperty real Layout::preferredHeight
 
     This property holds the preferred height of an item in a layout.
     If the preferred height is -1 it will be ignored, and the layout
@@ -198,14 +220,14 @@ void QQuickLayoutAttached::setPreferredHeight(qreal height)
 }
 
 /*!
-    \qmlproperty real Layout::maximumWidth
+    \qmlattachedproperty real Layout::maximumWidth
 
     This property holds the maximum width of an item in a layout.
     The default value is the items implicit maximum width.
 
     If the item is a layout, the implicit maximum width will be the maximum width the layout can
     have without any of its items grow beyond their maximum width.
-    The implicit maximum width for any other item is \c Number.POSITIVE_INFINITE.
+    The implicit maximum width for any other item is \c Number.POSITIVE_INFINITY.
 
     Setting this value to -1 will reset the width back to its implicit maximum width.
 
@@ -226,13 +248,13 @@ void QQuickLayoutAttached::setMaximumWidth(qreal width)
 }
 
 /*!
-    \qmlproperty real Layout::maximumHeight
+    \qmlattachedproperty real Layout::maximumHeight
 
     The default value is the items implicit maximum height.
 
     If the item is a layout, the implicit maximum height will be the maximum height the layout can
     have without any of its items grow beyond their maximum height.
-    The implicit maximum height for any other item is \c Number.POSITIVE_INFINITE.
+    The implicit maximum height for any other item is \c Number.POSITIVE_INFINITY.
 
     Setting this value to -1 will reset the height back to its implicit maximum height.
 
@@ -299,7 +321,7 @@ void QQuickLayoutAttached::setMaximumImplicitSize(const QSizeF &sz)
 }
 
 /*!
-    \qmlproperty bool Layout::fillWidth
+    \qmlattachedproperty bool Layout::fillWidth
 
     If this property is \c true, the item will be as wide as possible while respecting
     the given constraints. If the property is \c false, the item will have a fixed width
@@ -319,7 +341,7 @@ void QQuickLayoutAttached::setFillWidth(bool fill)
 }
 
 /*!
-    \qmlproperty bool Layout::fillHeight
+    \qmlattachedproperty bool Layout::fillHeight
 
     If this property is \c true, the item will be as tall as possible while respecting
     the given constraints. If the property is \c false, the item will have a fixed height
@@ -339,7 +361,7 @@ void QQuickLayoutAttached::setFillHeight(bool fill)
 }
 
 /*!
-    \qmlproperty int Layout::row
+    \qmlattachedproperty int Layout::row
 
     This property allows you to specify the row position of an item in a \l GridLayout.
 
@@ -357,7 +379,7 @@ void QQuickLayoutAttached::setRow(int row)
 }
 
 /*!
-    \qmlproperty int Layout::column
+    \qmlattachedproperty int Layout::column
 
     This property allows you to specify the column position of an item in a \l GridLayout.
 
@@ -376,7 +398,7 @@ void QQuickLayoutAttached::setColumn(int column)
 
 
 /*!
-    \qmlproperty Qt.Alignment Layout::alignment
+    \qmlattachedproperty Qt.Alignment Layout::alignment
 
     This property allows you to specify the alignment of an item within the cell(s) it occupies.
 
@@ -385,7 +407,7 @@ void QQuickLayoutAttached::setColumn(int column)
 
 
 /*!
-    \qmlproperty int Layout::rowSpan
+    \qmlattachedproperty int Layout::rowSpan
 
     This property allows you to specify the row span of an item in a \l GridLayout.
 
@@ -397,7 +419,7 @@ void QQuickLayoutAttached::setColumn(int column)
 
 
 /*!
-    \qmlproperty int Layout::columnSpan
+    \qmlattachedproperty int Layout::columnSpan
 
     This property allows you to specify the column span of an item in a \l GridLayout.
 
diff --git a/src/layouts/qquicklinearlayout.cpp b/src/layouts/qquicklinearlayout.cpp
index 13b582f9..7c48248b 100644
--- a/src/layouts/qquicklinearlayout.cpp
+++ b/src/layouts/qquicklinearlayout.cpp
@@ -48,33 +48,63 @@
 /*!
     \qmltype RowLayout
     \instantiates QQuickRowLayout
+    \inherits Item
     \inqmlmodule QtQuick.Layouts 1.0
     \ingroup layouts
     \brief Identical to \l GridLayout, but having only one row.
 
     It is available as a convenience for developers, as it offers a cleaner API.
 
+    Items in a RowLayout support these attached properties:
+    \list
+        \li \l{Layout::minimumWidth}{Layout.minimumWidth}
+        \li \l{Layout::minimumHeight}{Layout.minimumHeight}
+        \li \l{Layout::preferredWidth}{Layout.preferredWidth}
+        \li \l{Layout::preferredHeight}{Layout.preferredHeight}
+        \li \l{Layout::maximumWidth}{Layout.maximumWidth}
+        \li \l{Layout::maximumHeight}{Layout.maximumHeight}
+        \li \l{Layout::fillWidth}{Layout.fillWidth}
+        \li \l{Layout::fillHeight}{Layout.fillHeight}
+        \li \l{Layout::alignment}{Layout.alignment}
+    \endlist
     \sa ColumnLayout
     \sa GridLayout
+    \sa Row
 */
 
 /*!
     \qmltype ColumnLayout
     \instantiates QQuickColumnLayout
+    \inherits Item
     \inqmlmodule QtQuick.Layouts 1.0
     \ingroup layouts
     \brief Identical to \l GridLayout, but having only one column.
 
     It is available as a convenience for developers, as it offers a cleaner API.
 
+    Items in a ColumnLayout support these attached properties:
+    \list
+        \li \l{Layout::minimumWidth}{Layout.minimumWidth}
+        \li \l{Layout::minimumHeight}{Layout.minimumHeight}
+        \li \l{Layout::preferredWidth}{Layout.preferredWidth}
+        \li \l{Layout::preferredHeight}{Layout.preferredHeight}
+        \li \l{Layout::maximumWidth}{Layout.maximumWidth}
+        \li \l{Layout::maximumHeight}{Layout.maximumHeight}
+        \li \l{Layout::fillWidth}{Layout.fillWidth}
+        \li \l{Layout::fillHeight}{Layout.fillHeight}
+        \li \l{Layout::alignment}{Layout.alignment}
+    \endlist
+
     \sa RowLayout
     \sa GridLayout
+    \sa Column
 */
 
 
 /*!
     \qmltype GridLayout
     \instantiates QQuickGridLayout
+    \inherits Item
     \inqmlmodule QtQuick.Layouts 1.0
     \ingroup layouts
     \brief Provides a way of dynamically arranging items in a grid.
@@ -112,31 +142,27 @@
     specify the row span or column span by setting the \l{Layout::rowSpan}{Layout.rowSpan} or
     \l{Layout::columnSpan}{Layout.columnSpan} properties.
 
-    When the layout is resized, items may grow or shrink. Due to this, items have a
-    \l{Layout::minimumWidth}{minimum size}, \l{Layout::preferredWidth}{preferred size} and a
-    \l{Layout::maximumWidth}{maximum size}.
 
-    Preferred size may come from one of several sources. It can be specified with the
-    \l{Layout::preferredWidth}{Layout.preferredWidth} and
-    \l{Layout::preferredHeight}{Layout.preferredHeight} properties. If these properties are not
-    specified, it will use the items' \l{Item::implicitWidth}{implicitWidth} or
-    \l{Item::implicitHeight}{implicitHeight} as the preferred size.
-    Finally, if neither of these properties are set, it will use the \l{Item::width}{width} and
-    \l{Item::height}{height} properties of the item. Note that is provided only as a final
-    fallback. If you want to override the preferred size, you should use
-    \l{Layout::preferredWidth}{Layout.preferredWidth} or
-    \l{Layout::preferredHeight}{Layout.preferredHeight}.
-
-    The \l{Layout::fillWidth}{Layout.fillWidth} and \l{Layout::fillHeight}{Layout.fillHeight} can
-    either be \c true or \c false. If it is \c false, the items size will be fixed to its preferred
-    size. Otherwise, it will grow or shrink between its minimum and maximum size.
-
-    \note It is not recommended to have bindings to the width and height properties of items in a
-    GridLayout, since this would conflict with the goal of the GridLayout.
+    Items in a GridLayout support these attached properties:
+    \list
+        \li \l{Layout::row}{Layout.row}
+        \li \l{Layout::column}{Layout.column}
+        \li \l{Layout::rowSpan}{Layout.rowSpan}
+        \li \l{Layout::columnSpan}{Layout.columnSpan}
+        \li \l{Layout::minimumWidth}{Layout.minimumWidth}
+        \li \l{Layout::minimumHeight}{Layout.minimumHeight}
+        \li \l{Layout::preferredWidth}{Layout.preferredWidth}
+        \li \l{Layout::preferredHeight}{Layout.preferredHeight}
+        \li \l{Layout::maximumWidth}{Layout.maximumWidth}
+        \li \l{Layout::maximumHeight}{Layout.maximumHeight}
+        \li \l{Layout::fillWidth}{Layout.fillWidth}
+        \li \l{Layout::fillHeight}{Layout.fillHeight}
+        \li \l{Layout::alignment}{Layout.alignment}
+    \endlist
 
     \sa RowLayout
     \sa ColumnLayout
-
+    \sa Grid
 */