Doc: Update Extension example

-language review
-rewrite some paragraphs

Task-number: QTBUG-60635
Change-Id: I96154cd5d78b9517409ac67ec416c53031dcb909
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

1 files changed, 53 insertions, 47 deletions

diff --git a/examples/widgets/doc/src/extension.qdoc b/examples/widgets/doc/src/extension.qdoc
index d040fbb9ce..c895258acf 100644
--- a/examples/widgets/doc/src/extension.qdoc
+++ b/examples/widgets/doc/src/extension.qdoc
@@ -36,23 +36,21 @@
 
     \image extension-example.png Screenshot of the Extension example
 
-    The Extension application is a dialog that allows the user to
-    perform a simple search as well as a more advanced search.
+    The Extension application lets the user add search parameters in
+    a dialog and launch a simple or advanced search.
 
     The simple search has two options: \uicontrol {Match case} and \uicontrol
-    {Search from start}. The advanced search options include the
-    possibilities to search for \uicontrol {Whole words}, \uicontrol {Search
-    backward} and \uicontrol {Search selection}. Only the simple search is
-    visible when the application starts. The advanced search options
-    are located in the application's extension part, and can be made
-    visible by pressing the \uicontrol More button:
+    {Search from start}. The advanced search offers search for \uicontrol {Whole words},
+    \uicontrol {Search backward}, and \uicontrol {Search selection}.  The
+    application starts with simple search as the default. Click the \uicontrol More button
+    to show the advanced search options:
 
     \image extension_more.png Screenshot of the Extension example
 
     \section1 FindDialog Class Definition
 
-    The \c FindDialog class inherits QDialog. The QDialog class is the
-    base class of dialog windows. A dialog window is a top-level
+    The \c FindDialog class inherits QDialog. QDialog is the
+    base class for dialog windows. A dialog window is a top-level
     window mostly used for short-term tasks and brief communications
     with the user.
 
@@ -62,45 +60,53 @@
     displays the application's search options and controlling
     buttons.
 
-    In addition to a constructor, we declare the several child
-    widgets: We need a QLineEdit with an associated QLabel to let the
-    user type a word to search for, we need several  \l
-    {QCheckBox}{QCheckBox}es to facilitate the search options, and we
-    need three \l {QPushButton}{QPushButton}s: the \uicontrol Find button to
-    start a search and the \uicontrol More button to enable an advanced search.
-    Finally, we need a QWidget representing the application's extension
-    part.
+    In addition to the constructor, there are several child widgets:
+
+    \list
+    \li A QLineEdit with an associated QLabel to let the
+    user type a word to search for.
+    \li Several \l {QCheckBox}{QCheckBox}es to facilitate the search options.
+    \li Three \l {QPushButton}{QPushButton}s:
+        \list
+        \li the \uicontrol Find button to start a search
+        \li the \uicontrol More button to enable an advanced search
+        \li a QWidget representing the application's extension part
+        \endlist
+    \endlist
 
     \section1 FindDialog Class Implementation
 
-    In the constructor we first create the standard child widgets for
-    the simple search: the QLineEdit with the associated QLabel, two
-    of the \l {QCheckBox}{QCheckBox}es and all the \l
-    {QPushButton}{QPushButton}s.
+    Create the standard child widgets for the simple search in the constructor:
+    the QLineEdit with the associated QLabel, two {QCheckBox}es and all the
+    \l {QPushButton}{QPushButton}s.
 
     \snippet dialogs/extension/finddialog.cpp 0
 
-    We give the options and buttons a shortcut key using the &
-    character. In the \uicontrol {Find what} option's case, we also need to
-    use the QLabel::setBuddy() function to make the shortcut key work
-    as expected; then, when the user presses the shortcut key
-    indicated by the label, the keyboard focus is transferred to the
-    label's buddy widget, the QLineEdit.
-
-    We set the \uicontrol Find button's default property to true, using the
+    This snippet illustrates how you can define a shortcut key
+    for a widget. A shortcut should be defined by putting the ampersand
+    character (\c &) in front of the letter that should
+    become the shortcut.
+    For example, for \uicontrol {Find what}, pressing \uicontrol Alt
+    and \uicontrol w transfers focus to the QLineEdit widget.
+    Shortcuts can also be used for checking on or off a checkmark.
+    For example, pressing \uicontrol Alt and \uicontrol c puts the check mark
+    on \uicontrol {Match Case} if it was unchecked and vice versa.
+    It is the QLabel::setBuddy() method that links a widget to the shortcut
+    character if it has been defined.
+
+    Set the \uicontrol Find button's default property to true, using the
     QPushButton::setDefault() function. Then the push button will be
     pressed if the user presses the Enter (or Return) key. Note that a
     QDialog can only have one default button.
 
     \snippet dialogs/extension/finddialog.cpp 2
 
-    Then we create the extension widget, and the \l
-    {QCheckBox}{QCheckBox}es associated with the advanced search
-    options.
+    Create the extension widget, and the \l {QCheckBox}{QCheckBox}es associated
+    with the advanced search options.
 
     \snippet dialogs/extension/finddialog.cpp 3
 
-    Now that the extension widget is created, we can connect the \uicontrol
+    Now that the extension widget is created, connect the \uicontrol
     More button's \l{QAbstractButton::toggled()}{toggled()} signal to
     the extension widget's \l{QWidget::setVisible()}{setVisible()} slot.
 
@@ -111,26 +117,26 @@
     the status is true the widget is shown, otherwise the widget is
     hidden.
 
-    Since we made the \uicontrol More button checkable when we created it,
-    the connection makes sure that the extension widget is shown
-    depending on the state of \uicontrol More button.
+    Since the \uicontrol More button is checkable, the connection makes
+    sure that the extension widget is shown depending on the state of
+    the \uicontrol More button.
 
-    We also put the check boxes associated with the advanced
-    search options into a layout we install on the extension widget.
+    Create checkboxes associated with the advanced search options in
+    a layout installed on the extension widget.
 
     \snippet dialogs/extension/finddialog.cpp 4
 
-    Before we create the main layout, we create several child layouts
-    for the widgets: First we align the QLabel and its buddy, the
-    QLineEdit, using a QHBoxLayout. Then we vertically align the
-    QLabel and QLineEdit with the check boxes associated with the
-    simple search, using a QVBoxLayout. We also create a QVBoxLayout
-    for the buttons. In the end we lay out the two latter layouts and
-    the extension widget using a QGridLayout.
+    Before creating the main layout, create several child layouts
+    for the widgets. First align the QLabel and its buddy, the
+    QLineEdit, using a QHBoxLayout. Then align the QLabel and the QLineEdit
+    vertically with the checkboxes associated with the simple search,
+    using a QVBoxLayout. Create also a QVBoxLayout for the buttons.
+    Finally, lay out the two latter layouts and the extension widget
+    using a QGridLayout.
 
     \snippet dialogs/extension/finddialog.cpp 5
 
-    Finally, we hide the extension widget using the QWidget::hide()
+    Hide the extension widget using the QWidget::hide()
     function, making the application only show the simple search
     options when it starts. When the user wants to access the advanced
     search options, the dialog only needs to change the visibility of