PageIndicator: fix documentation review findings

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

2 files changed, 88 insertions, 1 deletions

diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-pageindicator-interactive.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-pageindicator-interactive.qml
new file mode 100644
index 00000000..88cadc27
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-pageindicator-interactive.qml
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** 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.Controls 2.0
+
+Pane {
+//! [1]
+SwipeView {
+    id: view
+    currentIndex: pageIndicator.currentIndex
+    anchors.fill: parent
+
+    Page {
+        title: qsTr("Home")
+    }
+    Page {
+        title: qsTr("Discover")
+    }
+    Page {
+        title: qsTr("Activity")
+    }
+}
+
+PageIndicator {
+    id: pageIndicator
+    interactive: true
+    count: view.count
+    currentIndex: view.currentIndex
+
+    anchors.bottom: parent.bottom
+    anchors.horizontalCenter: parent.horizontalCenter
+}
+//! [1]
+}
diff --git a/src/quicktemplates2/qquickpageindicator.cpp b/src/quicktemplates2/qquickpageindicator.cpp
index 04c6a344..0c1ed616 100644
--- a/src/quicktemplates2/qquickpageindicator.cpp
+++ b/src/quicktemplates2/qquickpageindicator.cpp
@@ -58,7 +58,28 @@ QT_BEGIN_NAMESPACE
 
     \image qtquickcontrols2-pageindicator.png
 
-    \snippet qtquickcontrols2-pageindicator.qml 1
+    \code
+    Column {
+        StackLayout {
+            id: stackLayout
+
+            Page {
+                // ...
+            }
+            Page {
+                // ...
+            }
+            Page {
+                // ...
+            }
+        }
+
+        PageIndicator {
+            currentIndex: stackLayout.currentIndex
+            count: stackLayout.count
+        }
+    }
+    \endcode
 
     \sa SwipeView, {Customizing PageIndicator}, {Indicator Controls}
 */
@@ -199,6 +220,14 @@ void QQuickPageIndicator::setCurrentIndex(int index)
     reacts to presses and automatically changes the \l {currentIndex}{current index}
     appropriately.
 
+    \snippet qtquickcontrols2-pageindicator-interactive.qml 1
+
+    \note Page indicators are typically quite small (in order to avoid
+    distracting the user from the actual content of the user interface). They
+    can be hard to click, and might not be easily recognized as interactive by
+    the user. For these reasons, they are best used to complement primary
+    methods of navigation (such as \l SwipeView), not replace them.
+
     The default value is \c false.
 */
 bool QQuickPageIndicator::isInteractive() const