Popup: fix some of the documentation review findings

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

1 files changed, 79 insertions, 7 deletions

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
 {