Popup: fix some of the documentation review findings

Change-Id: I69b60faab1588a45e005ba721c9796680bad6ac1
Task-number: QTBUG-55904
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

4 files changed, 159 insertions, 7 deletions

diff --git a/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-popup-custom.qml b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-popup-custom.qml
new file mode 100644
index 00000000..32025cc7
--- /dev/null
+++ b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-popup-custom.qml
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.6
+import QtQuick.Controls 2.0
+import QtQuick.Window 2.2
+
+Item {
+    id: root
+    width: 200
+    height: 200
+
+    Binding {
+        target: root
+        property: "visible"
+        value: root.Window.active
+    }
+//! [1]
+Popup {
+    background: Rectangle {
+        implicitWidth: 200
+        implicitHeight: 200
+        border.color: "#444"
+    }
+    contentItem: Column {}
+}
+//! [1]
+}
diff --git a/src/imports/controls/doc/src/includes/qquickpopup-padding.qdocinc b/src/imports/controls/doc/src/includes/qquickpopup-padding.qdocinc
new file mode 100644
index 00000000..31f5d2db
--- /dev/null
+++ b/src/imports/controls/doc/src/includes/qquickpopup-padding.qdocinc
@@ -0,0 +1,10 @@
+//! [padding]
+
+The padding properties are used to control the geometry of the
+\l {contentItem}{content item}.
+
+Popup uses the same approach to padding as \l {Control::padding}{Control}.
+For a visual explanation of the padding system, see the \l {Control Layout}
+section of the documentation.
+
+//! [padding]
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
index 559c89f0..852a1e03 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -489,6 +489,24 @@
         \snippet qtquickcontrols2-pane-custom.qml file
 
 
+    \section2 Customizing Popup
+
+        Popup consists of a \l {Popup::background}{background} and
+        \l {Popup::contentItem}{content item}.
+
+        \image qtquickcontrols2-popup-custom.png
+
+        \quotefromfile qtquickcontrols2-popup-custom.qml
+        \skipto import QtQuick 2.6
+        \printuntil import QtQuick.Controls 2.0
+        \codeline
+        \skipto Popup
+        \printuntil {
+        \printuntil }
+        \printuntil }
+        \printuntil }
+
+
     \section2 Customizing ProgressBar
 
         ProgressBar consists of two visual items: \l {Control::background}{background}
diff --git a/src/quicktemplates2/qquickpopup.cpp b/src/quicktemplates2/qquickpopup.cpp
index 6deda711..a3d68266 100644
--- a/src/quicktemplates2/qquickpopup.cpp
+++ b/src/quicktemplates2/qquickpopup.cpp
@@ -91,7 +91,10 @@ QT_BEGIN_NAMESPACE
     scene, it is recommended to use ApplicationWindow. ApplicationWindow also
     provides background dimming effects.
 
-    \sa {Popup Controls}, ApplicationWindow
+    Popup lays out its content in a similar fashion to \l Control. For more
+    information, see the \l {Control Layout} section of the documentation.
+
+    \sa {Popup Controls}, {Customizing Popup}, ApplicationWindow
 */
 
 /*!
@@ -820,6 +823,8 @@ QQuickPopup::~QQuickPopup()
     \qmlmethod void QtQuick.Controls::Popup::open()
 
     Opens the popup.
+
+    \sa visible
 */
 void QQuickPopup::open()
 {
@@ -835,6 +840,8 @@ void QQuickPopup::open()
     \qmlmethod void QtQuick.Controls::Popup::close()
 
     Closes the popup.
+
+    \sa visible
 */
 void QQuickPopup::close()
 {
@@ -850,6 +857,8 @@ void QQuickPopup::close()
     \qmlproperty real QtQuick.Controls::Popup::x
 
     This property holds the x-coordinate of the popup.
+
+    \sa y, z
 */
 qreal QQuickPopup::x() const
 {
@@ -867,6 +876,8 @@ void QQuickPopup::setX(qreal x)
     \qmlproperty real QtQuick.Controls::Popup::y
 
     This property holds the y-coordinate of the popup.
+
+    \sa x, z
 */
 qreal QQuickPopup::y() const
 {
@@ -910,7 +921,14 @@ void QQuickPopup::setPosition(const QPointF &pos)
     \qmlproperty real QtQuick.Controls::Popup::z
 
     This property holds the z-value of the popup. Z-value determines
-    the stacking order of popups. The default z-value is \c 0.
+    the stacking order of popups.
+
+    If two visible popups have the same z-value, the last one that
+    was opened will be on top.
+
+    The default z-value is \c 0.
+
+    \sa x, y
 */
 qreal QQuickPopup::z() const
 {
@@ -1075,7 +1093,8 @@ void QQuickPopup::setContentHeight(qreal height)
     \qmlproperty real QtQuick.Controls::Popup::availableWidth
     \readonly
 
-    This property holds the width available after deducting horizontal padding.
+    This property holds the width available to the \l contentItem after
+    deducting horizontal padding from the \l {Item::}{width} of the popup.
 
     \sa padding, leftPadding, rightPadding
 */
@@ -1089,7 +1108,8 @@ qreal QQuickPopup::availableWidth() const
     \qmlproperty real QtQuick.Controls::Popup::availableHeight
     \readonly
 
-    This property holds the height available after deducting vertical padding.
+    This property holds the height available to the \l contentItem after
+    deducting vertical padding from the \l {Item::}{height} of the popup.
 
     \sa padding, topPadding, bottomPadding
 */
@@ -1265,6 +1285,8 @@ void QQuickPopup::resetBottomMargin()
 
     This property holds the default padding.
 
+    \include qquickpopup-padding.qdocinc
+
     \sa availableWidth, availableHeight, topPadding, leftPadding, rightPadding, bottomPadding
 */
 qreal QQuickPopup::padding() const
@@ -1290,6 +1312,8 @@ void QQuickPopup::resetPadding()
 
     This property holds the top padding.
 
+    \include qquickpopup-padding.qdocinc
+
     \sa padding, bottomPadding, availableHeight
 */
 qreal QQuickPopup::topPadding() const
@@ -1315,6 +1339,8 @@ void QQuickPopup::resetTopPadding()
 
     This property holds the left padding.
 
+    \include qquickpopup-padding.qdocinc
+
     \sa padding, rightPadding, availableWidth
 */
 qreal QQuickPopup::leftPadding() const
@@ -1340,6 +1366,8 @@ void QQuickPopup::resetLeftPadding()
 
     This property holds the right padding.
 
+    \include qquickpopup-padding.qdocinc
+
     \sa padding, leftPadding, availableWidth
 */
 qreal QQuickPopup::rightPadding() const
@@ -1365,6 +1393,8 @@ void QQuickPopup::resetRightPadding()
 
     This property holds the bottom padding.
 
+    \include qquickpopup-padding.qdocinc
+
     \sa padding, topPadding, availableHeight
 */
 qreal QQuickPopup::bottomPadding() const
@@ -1492,6 +1522,14 @@ void QQuickPopup::setParentItem(QQuickItem *parent)
     \note If the background item has no explicit size specified, it automatically
           follows the popup's size. In most cases, there is no need to specify
           width or height for a background item.
+
+    \note Most popups use the implicit size of the background item to calculate
+    the implicit size of the popup itself. If you replace the background item
+    with a custom one, you should also consider providing a sensible implicit
+    size for it (unless it is an item like \l Image which has its own implicit
+    size).
+
+    \sa {Customizing Popup}
 */
 QQuickItem *QQuickPopup::background() const
 {
@@ -1518,6 +1556,17 @@ void QQuickPopup::setBackground(QQuickItem *background)
     popup is made visible, the content item is automatically reparented to
     the \l {ApplicationWindow::overlay}{overlay item} of its application
     window.
+
+    \note The content item is automatically resized to fit within the
+    \l padding of the popup.
+
+    \note Most popups use the implicit size of the content item to calculate
+    the implicit size of the popup itself. If you replace the content item
+    with a custom one, you should also consider providing a sensible implicit
+    size for it (unless it is an item like \l Text which has its own implicit
+    size).
+
+    \sa {Customizing Popup}
 */
 QQuickItem *QQuickPopup::contentItem() const
 {
@@ -1537,7 +1586,13 @@ void QQuickPopup::setContentItem(QQuickItem *item)
 
     This property holds the list of content data.
 
-    \sa Item::data
+    The list contains all objects that have been declared in QML as children
+    of the popup.
+
+    \note Unlike \c contentChildren, \c contentData does include non-visual QML
+    objects.
+
+    \sa Item::data, contentChildren
 */
 QQmlListProperty<QObject> QQuickPopup::contentData()
 {
@@ -1554,7 +1609,13 @@ QQmlListProperty<QObject> QQuickPopup::contentData()
 
     This property holds the list of content children.
 
-    \sa Item::children
+    The list contains all items that have been declared in QML as children
+    of the popup.
+
+    \note Unlike \c contentData, \c contentChildren does not include non-visual
+    QML objects.
+
+    \sa Item::children, contentData
 */
 QQmlListProperty<QQuickItem> QQuickPopup::contentChildren()
 {
@@ -1589,7 +1650,14 @@ void QQuickPopup::setClip(bool clip)
 /*!
     \qmlproperty bool QtQuick.Controls::Popup::focus
 
-    This property holds whether the popup has focus. The default value is \c false.
+    This property holds whether the popup wants focus.
+
+    When the popup actually receives focus, \l activeFocus will be \c true.
+    For more information, see \l {Keyboard Focus in Qt Quick}.
+
+    The default value is \c false.
+
+    \sa activeFocus
 */
 bool QQuickPopup::hasFocus() const
 {
@@ -1611,6 +1679,8 @@ void QQuickPopup::setFocus(bool focus)
     \readonly
 
     This property holds whether the popup has active focus.
+
+    \sa focus, {Keyboard Focus in Qt Quick}
 */
 bool QQuickPopup::hasActiveFocus() const
 {
@@ -1685,6 +1755,8 @@ void QQuickPopup::resetDim()
     \qmlproperty bool QtQuick.Controls::Popup::visible
 
     This property holds whether the popup is visible. The default value is \c false.
+
+    \sa open(), close()
 */
 bool QQuickPopup::isVisible() const
 {