1 files changed, 30 insertions, 12 deletions
diff --git a/src/quicktemplates2/qquickprogressbar.cpp b/src/quicktemplates2/qquickprogressbar.cpp
index 9c091ba1..d8ada6f4 100644
--- a/src/quicktemplates2/qquickprogressbar.cpp
+++ b/src/quicktemplates2/qquickprogressbar.cpp
@@ -48,23 +48,42 @@ QT_BEGIN_NAMESPACE
     \ingroup qtquickcontrols2-indicators
     \brief Indicates the progress of an operation.
 
+    \image qtquickcontrols2-progressbar.gif
+
     ProgressBar indicates the progress of an operation. The value should be updated
     regularly. The range is defined by \l from and \l to, which both can contain any value.
 
-    \table
-    \row \li \image qtquickcontrols2-progressbar-normal.png
-         \li A progress bar in its normal state.
-    \row \li \image qtquickcontrols2-progressbar-disabled.png
-         \li A progress bar that is disabled.
-    \endtable
-
     \code
     ProgressBar {
         value: 0.5
     }
     \endcode
 
-    \sa {Customizing ProgressBar}, BusyIndicator
+    ProgressBar also supports a special \l indeterminate mode, which is useful,
+    for example, when unable to determine the size of the item being downloaded,
+    or if the download progress gets interrupted due to a network disconnection.
+
+    \image qtquickcontrols2-progressbar-indeterminate.gif
+
+    \code
+    ProgressBar {
+        indeterminate: true
+    }
+    \endcode
+
+    The indeterminate mode is similar to a \l BusyIndicator. Both can be used
+    to indicate background activity. The main difference is visual, and that
+    ProgressBar can also present a concrete amount of progress (when it can be
+    determined). Due to the visual difference, indeterminate progress bars and
+    busy indicators fit different places in user interfaces. Typical places for
+    an indeterminate progress bar:
+    \list
+    \li at the bottom of a \l ToolBar
+    \li inline within the content of a \l Page
+    \li in an \l ItemDelegate to show the progress of a particular item
+    \endlist
+
+    \sa {Customizing ProgressBar}, BusyIndicator, {Indicator Controls}
 */
 
 class QQuickProgressBarPrivate : public QQuickControlPrivate
@@ -173,7 +192,7 @@ void QQuickProgressBar::setValue(qreal value)
 
     This property holds the logical position of the progress.
 
-    The position is defined as a percentage of the value, scaled to
+    The position is expressed as a fraction of the value, in the range
     \c {0.0 - 1.0}. For visualizing the progress, the right-to-left
     aware \l visualPosition should be used instead.
 
@@ -193,7 +212,7 @@ qreal QQuickProgressBar::position() const
 
     This property holds the visual position of the progress.
 
-    The position is defined as a percentage of the value, scaled to \c {0.0 - 1.0}.
+    The position is expressed as a fraction of the value, in the range \c {0.0 - 1.0}.
     When the control is \l {Control::mirrored}{mirrored}, \c visuaPosition is equal
     to \c {1.0 - position}. This makes \c visualPosition suitable for visualizing
     the progress, taking right-to-left support into account.
@@ -214,8 +233,7 @@ qreal QQuickProgressBar::visualPosition() const
     A progress bar in indeterminate mode displays that an operation is in progress, but it
     doesn't show how much progress has been made.
 
-    See below for an example:
-    \image qtquickcontrols2-progressbar-indeterminate.png
+    \image qtquickcontrols2-progressbar-indeterminate.gif
 
 */
 bool QQuickProgressBar::isIndeterminate() const