Qt Quick Layouts: Some small documentation refinements.

Document the unreliability of width and height.

Move the docs on how preferred size is determined to the overview
document instead of keeping it in the documentation for the Layout.*
attached property documentation, because its scope extends beyond this
class.

Task-number: QTBUG-34045 (inspired by)

Change-Id: Ie16f7d151b867aa45caf8e8e589f92ffd82e3220
Reviewed-by: Nico Vertriest <nico.vertriest@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

3 files changed, 43 insertions, 11 deletions

diff --git a/src/layouts/doc/src/qtquicklayouts-overview.qdoc b/src/layouts/doc/src/qtquicklayouts-overview.qdoc
index 0a4480f71..c1f432563 100644
--- a/src/layouts/doc/src/qtquicklayouts-overview.qdoc
+++ b/src/layouts/doc/src/qtquicklayouts-overview.qdoc
@@ -111,6 +111,47 @@
     Thus, the layout cannot be narrower than 156 or be taller or shorter than 150 without breaking
     any of the constraints of its child items.
 
+    \section2 Specifying Preferred Size
+    For each item, the effective preferred size may come from one of several candidate properties.
+    For determining the effective preferred size, it will query these candidate properties in the
+    following order, and use the first candidate with a valid width or height.
+
+    \table
+    \header
+        \li Candidate properties
+        \li Description
+    \row
+        \li \l{Layout::preferredWidth}{Layout.preferredWidth} or
+            \l{Layout::preferredHeight}{Layout.preferredHeight}
+        \li These properties are supposed to be modified by the application if the default implicit
+            size does not give the optimal arrangement.
+    \row
+        \li \l{Item::implicitWidth}{implicitWidth} or \l{Item::implicitHeight}{implicitHeight}
+        \li These properties are supposed to be supplied by each item to give a meaningful ideal size,
+            for example the size needed to display all the contents of a \l Text type.
+            An implicit width or height of \c 0 is interpreted as invalid.
+    \row
+        \li \l{Item::width}{width} and \l{Item::height}{height}
+        \li If none of the above properties are valid, the layout will resort to the
+            \l{Item::width}{width} and \l{Item::height}{height} properties.
+    \endtable
+
+    An item can specify \l{Layout::preferredWidth}{Layout.preferredWidth} without having to specify
+    \l{Layout::preferredHeight}{Layout.preferredHeight}. In this case, the effective preferred
+    height will be determined from the \l{Item::implicitHeight}{implicitHeight} (or ultimately
+    \l{Item::height}{height}).
+
+    \note Resorting to \l{Item::width}{width} or \l{Item::height}{height} properties is only
+    provided as a final fallback. If you want to override the preferred size, it is recommended to
+    use \l{Layout::preferredWidth}{Layout.preferredWidth} or
+    \l{Layout::preferredHeight}{Layout.preferredHeight}. Relying on the \l{Item::width}{width} or
+    \l{Item::height}{height} properties for specifying the preferred size might give some
+    unexpected behavior. For instance, changing the \l{Item::width}{width} or
+    \l{Item::height}{height} properties won't trigger a layout rearrangement. Also, when the layout
+    is forced to do a full rebuild it might use the actual width and height, and not the width and
+    height specified in the QML file.
+
+
     \section1 Connecting windows and layouts
     You can just use normal anchoring concepts to ensure that the layout will follow the window
     resizing.
diff --git a/src/layouts/qquicklayout.cpp b/src/layouts/qquicklayout.cpp
index 7eb2f8ea8..27de432f3 100644
--- a/src/layouts/qquicklayout.cpp
+++ b/src/layouts/qquicklayout.cpp
@@ -64,15 +64,6 @@
     \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.
diff --git a/src/layouts/qquicklinearlayout.cpp b/src/layouts/qquicklinearlayout.cpp
index 3909664da..2b1ce66ec 100644
--- a/src/layouts/qquicklinearlayout.cpp
+++ b/src/layouts/qquicklinearlayout.cpp
@@ -114,9 +114,9 @@
     \brief Provides a way of dynamically arranging items in a grid.
 
     If the GridLayout is resized, all items in the layout will be rearranged. It is similar
-    to the widget-based QGridLayout. All children of the GridLayout element will belong to
+    to the widget-based QGridLayout. All visible children of the GridLayout element will belong to
     the layout. If you want a layout with just one row or one column, you can use the
-    \l RowLayout or \l ColumnLayout. These offers a bit more convenient API, and improves
+    \l RowLayout or \l ColumnLayout. These offer a bit more convenient API, and improve
     readability.
 
     By default items will be arranged according to the \l flow property. The default value of