Document when anchors.fill can and can not be used

It seems to be a common mistake to manipulate the geometry of child
items. Be more explicit about it in the documentation.

Task-number: QTBUG-63303
Change-Id: I80fd4f1d194c9b001b76e0fb88877c7c0cf488da
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

2 files changed, 98 insertions, 1 deletions

diff --git a/src/quick/doc/snippets/qml/layout-simple.qml b/src/quick/doc/snippets/qml/layout-simple.qml
new file mode 100644
index 0000000000..6afdbe3ec9
--- /dev/null
+++ b/src/quick/doc/snippets/qml/layout-simple.qml
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.9
+import QtQuick.Layouts 1.2
+import QtQuick.Window 2.2
+
+//! [1]
+Window {
+    RowLayout {
+        anchors.fill: parent
+        //! [spacing]
+        spacing: 6
+        //! [spacing]
+        Rectangle {
+            color: 'azure'
+            Layout.preferredWidth: 100
+            Layout.preferredHeight: 150
+        }
+        Rectangle {
+            color: "plum"
+            Layout.fillWidth: true
+            Layout.fillHeight: true
+        }
+    }
+}
+//! [1]
diff --git a/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc b/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc
index 05e4465f2a..06ebe2d3d1 100644
--- a/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc
+++ b/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc
@@ -74,8 +74,31 @@
     \endlist
 
 
+    \section1 A Simple Layout
+
+    \snippet qml/layout-simple.qml 1
+
+    As the intention of using a layout is to rearrange its children whenever the layout changes
+    size, the application should make sure that the layout gets resized. In the above snippet the
+    RowLayout ensures that by specifying \c{anchors.fill: parent}. However, it can also be by other
+    means, such as directly specifying \l{Item::width}{width} and \l{Item::height}{height}
+    properties. In the same snippet, the \c azure Rectangle has a fixed size of \c{(100, 150)}
+    pixels, and the \c plum Rectangle will expand to occupy all the space it gets allocated.
+
+    \note A layout is responsible for its children's geometry. You should
+    therefore not specify \l{Item::width}{width}, \l{Item::height}{height}, \l{Item::x}{x},
+    \l{Item::y}{y} or any other properties that might influence those properties (such as
+    \l{Item::anchors}{anchors}) on those items. Otherwise there would be a conflict of interest,
+    and the result is undefined. This is also the case if the child item is a layout. Therefore,
+    only layouts with no parent layout can have \c{anchors.fill: parent}.
+
+    All items in the layout will have 6 pixels of spacing between them:
+
+    \snippet qml/layout-simple.qml spacing
+
+
+    \section2 Size Constraints
 
-    \section1 Size Constraints
     Since an item can be resized by its layout, the layout needs to know the
     \l{Layout::minimumWidth}{minimum}, \l{Layout::preferredWidth}{preferred},
     and \l{Layout::maximumWidth}{maximum} sizes of all items where \l{Layout::fillWidth}{Layout.fillWidth} or