[docs] Some more review of Application Manager's examples

Task-number: AUTOSUITE-927
Change-Id: Ibeffd5f70e00f5ad06d917029bd2901388e84ff9
Reviewed-by: Robert Griebl <robert.griebl@pelagicore.com>
 

6 files changed, 227 insertions, 204 deletions

diff --git a/examples/applicationmanager/animated-windows/doc/src/animated-windows.qdoc b/examples/applicationmanager/animated-windows/doc/src/animated-windows.qdoc
index 4ba2a4ea..d412054c 100644
--- a/examples/applicationmanager/animated-windows/doc/src/animated-windows.qdoc
+++ b/examples/applicationmanager/animated-windows/doc/src/animated-windows.qdoc
@@ -41,7 +41,7 @@ This example shows you how to animate windows to appear and disappear, in a Syst
 \b Prerequisites: You're already familiar with the concepts and topics introduced in the
    \l {"Hello World!" System UI Example}.
 
-Unlike with the \l {"Hello World!" System UI Example} {Hello World} example, most Graphical User
+Unlike with the \l{"Hello World!" System UI Example}{Hello World} example, most Graphical User
 Interfaces (GUIs) avoid making sudden, abrupt, changes as they can confuse the user and are not
 visually pleasant. So, when the WindowManager creates a new WindowObject, we want to animate its
 appearance instead of simply having it pop up on the screen. Likewise, once a WindowObject loses
@@ -49,7 +49,7 @@ its surface - because the application closed this window or stopped altogether -
 from the WindowManager's model, we want to animate its disappearance instead of having it vanish
 immediately.
 
-If you're using a ready-made, advanced, layout such as ListView, you can assign Transitions to
+If you're using a ready-made, advanced layout such as ListView, you can assign Transitions to
 different actions like add, remove, displaced, and so on, and keep using WindowManager as your
 model. But in many situations this is not the case. Instead, you have to create your own model,
 such as a ListModel, so that a WindowObject only leaves the model when you have finished
@@ -73,7 +73,7 @@ finished.
 \skipto property bool safeToRemove
 \printuntil onSafeToRemoveChanged
 
-Then, we add a WindowObject to it, and have it displayed on screen as soon as WindowManager creates
+Then, we add a WindowObject to it, and display it on screen as soon as WindowManager creates
 a WindowObject.
 
 \skipto Connections
diff --git a/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc b/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc
index 0702fe5a..2f819c32 100644
--- a/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc
+++ b/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc
@@ -29,77 +29,72 @@
 /*!
 
 \example applicationmanager/custom-appman
-\title Implementing a Custom Application-Manager Example
+\title Implement a Custom Application Manager Example
 \image custom-appman.png Screenshot
-\brief Basic structure and starting point for a custom application-manager executable.
+\brief Provides the basic structure and starting point for a custom application manager executable.
 \ingroup applicationmanager-examples
 
 \section1 Introduction
 
-The application-manager is compiled as a self-contained executable that can be configured
-in large parts through the YAML based config file system and startup plugins. However it may still
-be necessary to implement a custom application-manager executable to have more influence over the
-startup behavior.
+The application manager is compiled as a self-contained executable that can be configured in large
+parts through the YAML-based config file system and startup plugins. However, if you need to have
+more control over the application's startup behavior, it may be necessary to implement a custom
+application manager executable.
 
-\note Please note however, that all C++ classes in the application-manager modules are considered private
-API at the moment, so there are no compatibility guarantees at all.
+\note Currently, all C++ classes in the application manager modules are considered private API, so
+there are no compatibility guarantees at all.
 
-If you still desire to go down that road however, this example will provide you with an starting
-point to build your custom implementation upon.
+If you still require this behavior, this example provides a starting point that you can build your
+custom implementation upon. Keep in mind, that this custom application manager executable needs a
+System UI to display something on the screen, just like the standard \c appman executable.
 
-Keep in mind though, that this custom application-manager executable will need a System-UI to
-display something on the screen, just as the standard \c appman executable.
-
-\section1 Walkthrough
-
-Following is a breakdown of the minimal code needed for such a custom implementation:
+The following is a breakdown of the minimal code necessary:
 
 \quotefromfile applicationmanager/custom-appman/custom-appman.cpp
 \skipto #include
 \printuntil QT_USE_NAMESPACE_AM
 
-The application-manager is split into functional building blocks/libraries. These includes will
-pull in the basic set of classes needed.
-In order to avoid possible clashes with QML plugins, all of the application-manager's symbols are
-namespaced - \c QT_USE_NAMESPACE_AM will expand to the matching \c using statement.
+The application manager is split into functional building blocks. These include statements
+pull in the basic set of classes that you need. To avoid possible clashes with QML plugins, all of
+the application manager's symbols are namespaced - \c QT_USE_NAMESPACE_AM expands to the equivalent
+\c using statement.
 
 \skipto QCoreApplication::setApplicationName
 \printuntil QCoreApplication::setApplicationVersion
 
-Not application-manager specific, but having an application name and version set is generally
-a good idea.
+Generally, it's a good idea to set an application name and version.
 
 \printline Logging::init
 
-We want the logging part of the application-manager initialized as early as possible, especially
-when dealing with DLT logging.
+We want the application manager's logging part to be initialized as early as possible, especially
+when we are dealing with DLT logging.
 
 \printline Package::ensure
 
-If you are using the installer part of the application-manager, this function needs to be called
-\e before the QApplication constructor to make sure your C locale is an UTF-8 variant (this is a
-requirement in order to get deterministic results when using \c libarchive with non-ASCII filenames).
+If you are using the application manager's installer part, this function needs to be called
+\e before the QApplication constructor to make sure that your C locale is a UTF-8 variant. This is
+a requirement, to get deterministic results when using \c libarchive with non-ASCII filenames.
 
 \printline Sudo::forkServer
 
 Again, for the installer part only, an additional setup step is necessary before running the
-QApplication constructor: if the executable is setuid-root, this call will \c fork of a child
-process which keeps the root privileges while the main process permanently drop them.
+QApplication constructor: if the executable is setuid-root, this call will \c fork off a child
+process which keeps the root privileges while the main process permanently drops them.
 
 \printuntil return 2
 \printline }
 
-This \c try block is the heart of the custom application-manager. You need to create a \c Main
-(which is a class derived from QGuiApplication) object plus a suitable configuration object: in
-this simple case we just use the application-manager's default YAML parsing, so we instantiate
-a \c DefaultConfiguration object.
-The rest of the function consists of parsing the configuration and then calling the relevant
-setup routines on the \c Main object.
-Since \c Main can be derived differently depending on your application-manager configuration
-(headless, with widgets or standard), you would need to know the correct base-class for the exec()
-call - the \c MainBase typedef will circumvent that problem though.
-
-Keep in mind that most functions in the application-manager will throw exceptions that are
-derived from \c std::exception, so a \c catch handler is a must.
+This \c try block is the heart of the custom application manager. You need to create a \c Main
+object, which is a class derived from QGuiApplication, plus a suitable configuration object. In
+this simple case, we use the application manager's default YAML parsing, so we instantiate a
+\c DefaultConfiguration object. The rest of the function involves parsing the configuration and
+then calling the relevant setup routines on the \c Main object.
+
+Depending on your application manager's configuration, the \c Main object can be derived
+differently: headless, with widgets, or standard. So, you need to know the correct base class for
+the exec() call. However, the \c MainBase typedef circumvents this problem.
+
+Most functions in the application manager throw exceptions that are derived from \c std::exception,
+so a \c catch handler is compulsory.
 
 */
diff --git a/examples/applicationmanager/minidesk/doc/src/minidesk.qdoc b/examples/applicationmanager/minidesk/doc/src/minidesk.qdoc
index 02d58ce5..ba4a1b52 100644
--- a/examples/applicationmanager/minidesk/doc/src/minidesk.qdoc
+++ b/examples/applicationmanager/minidesk/doc/src/minidesk.qdoc
@@ -29,50 +29,49 @@
 /*!
 
 \example applicationmanager/minidesk
-\title Desktop System-UI Example
+\title Desktop System UI Example
 \image minidesk.png Screenshot
-\brief Minimal Desktop System-UI in pure QML.
+\brief Illustrates a minimal Desktop System UI in pure QML.
 \ingroup applicationmanager-examples
 
 \section1 Introduction
 
-The \e {Desktop System-UI Example} showcases the application-manager API in a simple fashion. The
-focus is on the concepts, less on elegance or completeness, for instance no error checking is done.
-Some features will only print debug messages without further functionality. A classic desktop with
-server-side window decorations is emulated.
+This example showcases the application manager API in a simple way, as a classic desktop with
+server-side window decorations. The example focuses more on the concepts, but less on elegance or
+completeness. For example, there's no error checking done. Some features in this minimal Desktop
+System only print debug messages.
 
 The following features are supported:
 \list
-\li Start applications by clicking an icon on the top left
-\li Stop an application by clicking the icon on the top left again
-\li Close application windows by clicking on the top/left window decoration rectangle
-\li Raise applications by clicking on the decoration
-\li Drag windows by pressing on the window decoration and moving them
-\li System-UI sends 'propA' change when an app is started
-\li System-UI and App2 react on window property changes with a debug message
-\li App1 animation can be stopped and restarted by a click
-\li App1 sends rotation angle as a window property to System-UI on stop
-\li App1 shows a pop-up on the System-UI while it is paused
-\li App2 will make use of an IPC extension when it is started
-\li App2 logs the document URL it has been started with
-\li App2 triggers a notification in the System-UI when the bulb icon is clicked
-\li Wayland client windows from processes started outside of appman will be shown
+    \li Start applications by clicking on an icon in the top left
+    \li Stop an application by clicking on the icon in the top left again
+    \li Close application windows by clicking on the top left window decoration rectangle
+    \li Bring applications forward by clicking on the decoration
+    \li Drag windows by pressing on the window decoration and moving them
+    \li The System UI sends a 'propA' change when an app starts
+    \li The System UI and App2 react to window property changes with a debug message
+    \li Stop or restart App1 animations with a click
+    \li App1 sends rotation angle as a window property to System UI on stop
+    \li App1 shows a pop up on the System UI when it is paused
+    \li App2 makes use of an IPC extension when it starts
+    \li App2 logs the document URL that started it
+    \li App2 triggers a notification in the System UI, when the bulb icon is clicked
+    \li Show Wayland client windows that originate from processes outside of \c appman
 \endlist
 
-\note The example can be run in single- and multi-process mode. In the following, multi-process is
-assumed and corresponding terminology is used. The terms \e client and \e application, respectively
-\e server and \e {System-UI} are used interchangeably. The System-UI comprises compositing and
-generic inter-process communication (IPC).
+\note This example can be run in single-process or multi-process mode. In the walkthrough below, we
+use multi-process and its corresponding terminology. The terms \e client and \e application;
+\e server and \e {System UI} are used interchangeably. The System UI comprises both compositing and
+generic Inter-Process Communication (IPC).
 
-\section2 Invocation
-The example can be started from within the minidesk folder with:
+To start the example, navigate to the \c minidesk folder, and run the following command:
 \badcode
-path/to/bin/appman -c am-config.yaml -r
+<path-to-appman.bin>/ -c am-config.yaml -r
 \endcode
 
 \section1 Walkthrough
 
-\section2 System-UI Window
+\section2 System UI Window
 
 \quotefromfile applicationmanager/minidesk/system-ui/main.qml
 \skipto import Qt
@@ -80,148 +79,158 @@ path/to/bin/appman -c am-config.yaml -r
 \printline }
 \dots
 
-The \l{QtApplicationManager.SystemUI} module has to be imported to be able to access the application-manager
-APIs. The System-UI window has a fixed size and linen background color. Instead of a \l{Rectangle},
-the root element could as well be a \l{Window}. On top of the background the
-\l{applicationmanager/minidesk/system-ui/Readme.qml}{Readme} element is shown that displays a usage how-to. At the
-bottom left there is a textual indication for whether the application-manager runs in single- or
-multi-process mode.
+The \l{QtApplicationManager.SystemUI} module has to be imported to access the application manager
+APIs. The System UI window has a fixed size and linen background color. Instead of a \l{Rectangle},
+the root element could also be a \l{Window}. On top of the background, we display a
+\l{applicationmanager/minidesk/system-ui/Readme.qml}{Readme} element with information on the
+features available. At the bottom left there is a textual indication for whether the
+application manager runs in single-process or multi-process mode.
 
 \section2 Launcher
 
 \printto System-UI chrome for applications
 
-A \l{Repeater} provides the application icons arranged in a \l{Column} on the top-left corner of
-the System-UI. This is achieved by using the \l{ApplicationManager} element as the model. Amongst
-others, it provides the \c icon role which is used as the \l{Image} source URL. The \c icon URL is
-defined in the \l{Manifest Definition}{info.yaml} file of the application. To indicate that an
-application has been launched, the opacity of the corresponding application's icon is decreased
-through a binding to the \c isRunning role.
+A \l{Repeater} provides the application icons arranged in a \l{Column} on the top left corner of
+the System UI; the \l{ApplicationManager} element is the model. Among others, the
+ApplicationManager provides the \c icon role which is used as the \l{Image} source URL. The
+\c icon URL is defined in the application's \l{Manifest Definition}{info.yaml} file. To indicate
+that an application has launched, the corresponding application icon's opacity is decreased by
+binding it to the \c isRunning role.
 
-Clicking on an application icon will launch the corresponding application through a call to
-\l {ApplicationObject::start()}{ApplicationObject.start()} that is accessible through the
-\c application role in the ApplicationManager model. Both applications will be started with
-the (optional) document URL "documentUrl". If the application is already running,
-\l {ApplicationObject::stop()}{ApplicationObject.stop()} will be called instead.
+Clicking on an application icon launches the corresponding application through a call to
+\l {ApplicationObject::start()}{ApplicationObject.start()}. This function is accessible through
+the \c application role in the ApplicationManager model. Both applications start with
+the (optional) document URL, \c documentUrl. If the application is already running,
+\l {ApplicationObject::stop()}{ApplicationObject.stop()} is called instead.
 
-\section2 Application Windows in the System-UI
+\section2 Application Windows in the System UI
 
 \printto System-UI for a pop-up
 
 This second Repeater provides the window chrome for the application windows in its delegate. The
-model is a plain ListModel fed with \l{WindowObject}{window objects} as they get created by the
-WindowManager. The code that populates the window role of this ListModel will be shown below. For
+model is a plain ListModel fed with \l{WindowObject}{window objects} as they are created by the
+WindowManager. The code that populates the window role of this ListModel is shown below. For
 now let's focus on what this Repeater's delegate consists of:
+
 \list
-\li A fixed size window container \l{Rectangle} with a "tan" color. The location depends on the
-    \c model.index, hence each application window has a different initial location.
-\li The name of the application that created that window, prefixed with "Decoration" on the top
-    horizontal center. The name is provided by the ApplicationObject related to that window and is
-    defined in the application's \l{Manifest Definition}{info.yaml} file.
-\li A MouseArea for dragging and raising the window. The MouseArea fills the entire window. The
-    WindowItem containing the application's window is placed on top of it and hence it will not
-    handle dragging.
-\li A small chocolate-colored \l Rectangle on the top left corner for closing the window (see
-    \l{WindowObject::close()}{WindowObject.close()}). Since our sample applications only have one
-    top-level window, closing it will also cause the corresponding application to quit.
-\li The centerpiece: a \l WindowItem to render the \c WindowObject in the SystemUI. That's similar
-    to the relationship between image files and QML's Image component.
-\li And finally code to remove a row from the ListModel once its window has been destroyed from the
-    client (application) side - either because it was closed, made invisible, or the application
-    itself quit or crashed. Any of these cases results in the \l WindowObject losing its surface.
-    A more sophisticated System-UI could animate the disappearance of a window. For that please
-    check the \l {Animated Windows System-UI Example}
+    \li A fixed size window container \l{Rectangle} in "tan" color. The location depends on the
+        \c model.index, hence each application window has a different initial location.
+    \li The name of the application that created that window, prefixed with "Decoration" on top.
+        This name is from the related ApplicationObject, defined in the application's
+        \l{Manifest Definition}{info.yaml} file.
+    \li A MouseArea for dragging and raising the window. The MouseArea fills the entire window. The
+        WindowItem containing the application's window is placed on top of it and hence it will not
+        handle dragging.
+    \li A small chocolate-colored \l Rectangle on the top left corner for closing the window (see
+        \l{WindowObject::close()}{WindowObject.close()}). Since our sample applications only have one
+        top-level window, closing it causes the corresponding application to quit.
+    \li The centerpiece: a \l WindowItem to render the \c WindowObject in the SystemUI; similar to
+        the relationship between image files and QML's Image component.
+    \li And finally code to remove a row from the ListModel once its window has been destroyed from
+        the application (client) side - either because it was closed, made invisible, or the
+        application itself quit or crashed. Any of these cases results in the \l WindowObject
+        losing its surface. A more sophisticated System UI could animate the disappearance of a
+        window, as illustrated in the \l {Animated Windows System UI Example}.
 \endlist
 
 \section2 Pop-ups
 
-Two approaches are implemented to display pop-ups in the System-UI:
+Two approaches are implemented to display pop-ups in the System UI:
+
 \list
-\li Through a window rendered by the client application
-\li Through the notification API provided by the application-manager
+    \li Through a window rendered by the client application
+    \li Through the notification API provided by the application manager
 \endlist
+
 This is the corresponding System-UI code:
 \printto Handler for WindowManager signals
 
 \section3 Client Application Rendering
+
 App1 instantiates another \l{ApplicationManagerWindow} for the pop-up within its
 \l{ApplicationManagerWindow} root element, as shown here:
+
 \quotefromfile applicationmanager/minidesk/apps/tld.minidesk.app1/app1.qml
 \skipto Rectangle
 \skipto ApplicationManagerWindow
 \printuntil Component.onCompleted
 \printline }
+
 The \l{ApplicationManagerWindow::setWindowProperty}{ApplicationManagerWindow.setWindowProperty()}
 method is used to set a freely selectable shared property. Here we chose \c{type: "pop-up"} to
-indicate that the window is supposed to be shown as a pop-up. In the
-WindowManager::onWindowAdded() handler below the System-UI
-checks this property and handles the window appropriately as a pop-up.
+indicate that the window is supposed to be shown as a pop-up.
+
+In the WindowManager::onWindowAdded() signal handler \l{WindowManager Signal Handler}{below}, the
+SystemUI checks this property and handles the window appropriately as a pop-up.
 
 A pop-up window will be set as the content window of the \c popUpContainer WindowItem in the
-SystemUI code above. For demonstration purposes the implementation supports only one pop-up at a
+SystemUI code above. For demonstration purposes, the implementation supports only one pop-up at a
 time. This is sufficient, since only App1 will display a single pop-up when its animation is
-paused. In general it is essential to understand, that there has to be an agreement between the
-SystemUI and applications in terms of how windows are mapped. In contrast to regular application
-windows that are freely draggable and have title bars and borders, the pop-up window is just
-centered and has no decoration at all. Note also how the
-\l{WindowObject::contentState}{WindowObject.contentStateChanged} signal is handled in
-the \c popUpContainer: the window is released when it has no surface associated any more. This is
+paused. It is essential to understand, that there has to be an agreement between the System UI
+and applications, in terms of how windows are mapped. In contrast to regular application windows
+that are freely draggable and have title bars and borders, the pop-up window is just centered and
+has no decoration at all. Note also how the
+\l{WindowObject::contentState}{WindowObject.contentStateChanged} signal is handled in the
+\c popUpContainer: the window is released when it has no surface associated any more. This is
 important to free any resources that the \l{WindowObject}{window} object is using. Note that this
-is done implicitly when the WindowManager model is used directly. This approach is more convenient
-and should be preferred.
+is done implicitly when the WindowManager model is used directly. This approach is recommended as
+it's more convenient.
 
 \section3 Notification API Usage
 
 An alternative to the window property approach is to use the application-manager's \l{Notification}
-API on the application (client) side and the \l{NotificationManager} API on the System-UI (server)
-side. The following code is invoked when the \e bulb icon of App2 is clicked:
+API on the application (client) side and the \l{NotificationManager} API on the System UI (server)
+side. The following code is invoked when you click on the \e bulb icon in App2:
 
 \quotefromfile applicationmanager/minidesk/apps/tld.minidesk.app2/app2.qml
 \skipto var notification
 \printuntil notification.show();
 
 App2 creates a new \l{Notification} element, sets its \l{Notification::summary}{summary} property
-and calls \l{Notification::show()}{show()} on it. This call will increase the
-\l{NotificationManager::count}{NotificationManager.count} on the System-UI side, and subsequently
+and calls \l{Notification::show()}{show()} on it. This call increases the
+\l{NotificationManager::count}{NotificationManager.count} on the System UI side, and subsequently
 the \l{Text} element's text property will be set to the \c summary string of the first
-notification. Presenting the first notification only is a simplification to keep the code short.
+notification. For brevity, the example only presents the first notification.
 
 \section2 WindowManager Signal Handler
 
 \quotefromfile applicationmanager/minidesk/system-ui/main.qml
 \skipto Handler for WindowManager signals
 \printto IPC extension
-This is the vital part of the System-UI, where the window (surfaces) of the applications are mapped
-to \l{WindowItem}s in the System-UI. The \l {WindowManager::windowAdded}{onWindowAdded} handler is
-invoked when a new application window is available (becomes visible).
-
-Only the "pop-up" ApplicationManagerWindow of App1 has the user-defined \c type property set. Such
-a window is placed in the \c popUpContainer WindowItem. All other windows don't have a \c type
-property. Those windows are added to the \c topLevelWindowsModel. This model is used in the
-SystemUI chrome Repeater above. Consequently, the \l {WindowObject}{window} object passed as an
-argument to \l {WindowManager::windowAdded}{onWindowAdded} is set as the
+
+This is the vital part of the System UI, where the window (surfaces) of the applications are mapped
+to \l{WindowItem}s in the SystemUI. When a new application window is available (becomes visible),
+the \l {WindowManager::windowAdded}{onWindowAdded} handler is invoked.
+
+Only App1's "pop-up" ApplicationManagerWindow has the user-defined \c type property set. Such a
+window is placed in the \c popUpContainer WindowItem. All other windows don't have a \c type
+property; they are added to the \c topLevelWindowsModel. This model is used in the SystemUI chrome
+Repeater above. Consequently, the \l {WindowObject}{window} object passed as an argument to
+\l {WindowManager::windowAdded}{onWindowAdded} is set as the
 \l{WindowItem::window}{window} property of the WindowItem (within the Repeater's delegate).
 
-By the way, any wayland client window from a process started outside of the application manager
-will also be displayed since "\c flags/noSecurity: \c yes" is set in the configuration file, for
-instance (KDE's Calculator):
+Incidentally, any Wayland client window from a process started outside of the application manager
+will also be displayed since in the configuration file, "\c flags/noSecurity: \c yes" is set, for
+instance in KDE's Calculator:
 
 \badcode
 $ QT_WAYLAND_DISABLE_WINDOWDECORATION=1 QT_WAYLAND_SHELL_INTEGRATION=xdg-shell-v5 kcalc -platform wayland
 \endcode
 
-\section2 IPC Extension
+\section2 Inter-Process Communication (IPC) Extension
+
 The following snippet demonstrates how the \l{ApplicationIPCInterface} can be used to define an IPC
-extension. The IPC interface has to be defined in the System-UI, for instance:
+extension. The IPC interface has to be defined in the System UI, for instance:
+
 \printuntil Component.onCompleted
 \printline }
 
-Here, a property \c pi is defined, as well as a signal \c computed and a function \c circumference.
+Here, a \c pi property is defined, as well as a \c computed signal and a \c circumference function.
 After registering this interface with
 \l{ApplicationIPCManager::registerInterface()}{ApplicationIPCManager.registerInterface()}, it can
 be used from the application processes.
 
-On the application side, the \l{ApplicationInterfaceExtension} type has to be used. Here is how
+On the application side, the \l{ApplicationInterfaceExtension} type has to be used. Here's how
 App2 makes use of this interface extension:
 
 \quotefromfile applicationmanager/minidesk/apps/tld.minidesk.app2/app2.qml
@@ -229,23 +238,25 @@ App2 makes use of this interface extension:
 \printuntil onPiChanged
 \printline }
 
-The interface is used here immediately when it becomes ready. It can, of course, be accessed from
-elsewhere, too. The \l{ApplicationInterfaceExtension::name}{ApplicationInterfaceExtension.name} has
-to match the name it was registered with in
+The interface is used here as soon as it's ready. Of course, the interface can be accessed from
+elsewhere, too. The \l{ApplicationInterfaceExtension::name}{ApplicationInterfaceExtension.name}
+must match the name it was registered with in
 \l{ApplicationIPCManager::registerInterface()}{ApplicationIPCManager.registerInterface()}.
 
 \section2 Application Termination
-When an application is stopped from the System-UI through
-\l{ApplicationManager::stopApplication()}{ApplicationManager.stopApplication()}, it will be sent
-the \l{ApplicationInterface::quit()}{ApplicationInterface.quit()} signal. The application can do
-some clean-up and must subsequently confirm with
+
+When an application is stopped from the System UI through
+\l{ApplicationManager::stopApplication()}{ApplicationManager.stopApplication()}, it is sent
+the \l{ApplicationInterface::quit()}{ApplicationInterface.quit()} signal. Then, the application can
+do some clean-up and it must subsequently confirm with
 \l{ApplicationInterface::acknowledgeQuit()}{ApplicationInterface.acknowledgeQuit()}, like App2 does:
+
 \quotefromfile applicationmanager/minidesk/apps/tld.minidesk.app2/app2.qml
 \skipto Connections
 \printuntil onQuit
 \printline }
 
 Note that App1 is not well-behaved: it does not acknowledge the \c quit signal and will hence simply
-be terminated by the application-manager.
+be terminated by the application manager.
 
 */
diff --git a/examples/applicationmanager/minidesk/system-ui/Readme.qml b/examples/applicationmanager/minidesk/system-ui/Readme.qml
index 38a5c113..cec945e2 100644
--- a/examples/applicationmanager/minidesk/system-ui/Readme.qml
+++ b/examples/applicationmanager/minidesk/system-ui/Readme.qml
@@ -74,20 +74,20 @@ Item {
             color: "grey"
             font.pixelSize: 16
             text: "The following features are supported:\n" +
-                  "\u2022 Start applications by clicking an icon on the top left\n" +
-                  "\u2022 Stop an application by clicking the icon on the top left again\n" +
-                  "\u2022 Close an application window by clicking on the top/left window decoration rectangle\n" +
-                  "\u2022 Raise applications by clicking on the decoration\n" +
+                  "\u2022 Start applications by clicking on an icon in the top left\n" +
+                  "\u2022 Stop an application by clicking on the icon in the top left again\n" +
+                  "\u2022 Close application windows by clicking on the top left window decoration rectangle\n" +
+                  "\u2022 Bring applications forward by clicking on the decoration\n" +
                   "\u2022 Drag windows by pressing on the window decoration and moving them\n" +
-                  "\u2022 System-UI sends 'propA' change when an app is started\n" +
-                  "\u2022 System-UI and App2 react on window property changes with a debug message\n" +
-                  "\u2022 App1 animation can be stopped and restarted by a click\n" +
-                  "\u2022 App1 sends rotation angle as a window property to System-UI on stop\n" +
+                  "\u2022 The System UI sends a 'propA' change when an app starts\n" +
+                  "\u2022 The System UI and App2 react to window property changes with a debug message\n" +
+                  "\u2022 Stop or restart App1 animations with a click\n" +
+                  "\u2022 App1 sends rotation angle as a window property to System UI on stop\n" +
                   "\u2022 App1 shows a pop-up on the System-UI while it is paused\n" +
-                  "\u2022 App2 will make use of an IPC extension when it is started\n" +
-                  "\u2022 App2 logs the document URL it has been started with\n" +
-                  "\u2022 App2 triggers a notification in the System-UI when the bulb icon is clicked\n" +
-                  "\u2022 Wayland client windows from processes started outside of appman will be shown"
+                  "\u2022 App2 makes use of an IPC extension when it starts\n" +
+                  "\u2022 App2 logs the document URL that started it\n" +
+                  "\u2022 App2 triggers a notification in the System UI when the bulb icon is clicked\n" +
+                  "\u2022 Show Wayland client windows that originate from processes outside of \c appman"
         }
     }
 }
diff --git a/examples/applicationmanager/multi-views/doc/src/multi-views.qdoc b/examples/applicationmanager/multi-views/doc/src/multi-views.qdoc
index e00a091a..959b3dd7 100644
--- a/examples/applicationmanager/multi-views/doc/src/multi-views.qdoc
+++ b/examples/applicationmanager/multi-views/doc/src/multi-views.qdoc
@@ -29,31 +29,40 @@
 /*!
 
 \example applicationmanager/multi-views
-\title Multiple Views per Window System-UI Example
-\image multi-views.png
-\brief A WindowObject being rendered by multiple WindowItems.
+\brief Learn how to render a WindowObject using multiple WindowItems.
 \ingroup applicationmanager-examples
+\title Multiple Views per Window System UI Example
+\image multi-views.png
+
+\section1 Introduction
+
+This example shows you how to assign the same WindowObject to multiple WindowItems, resulting in
+the same surface being rendered multiple times on screen. The example also illustrates the pros
+and cons of a primary window.
+
+\b Prerequisites: You're already familiar with the concepts and topics introduced in the
+   \l{Animated Windows System UI Example}.
+
+The button on the top left of the screen shows an icon, a cog, for the only built-in application
+in this example. Overlayed on this icon is the action taken when you click on it. \uicontrol Start
+is shown when the application is not running, and clicking on it calls
+\l{ApplicationObject::start}{ApplicationObject.start}. Otherwise, the button shows \uicontrol Stop
+and the corresponding action is taken when clicked.
+
+When the application starts, its sole window is shown, decorated with a title bar and borders.
+The title bar displays \uicontrol Primary if \l{WindowItem::primary}{WindowItem.primary} is true;
+\uicontrol Secondary otherwise.
+
+Then, comes the name of the application that created the window, which in this case is \b App1.
+On the far left of a window's title bar is a minus button (-) that destroys its WindowItem. On the
+far right, there's a plus (+) button that creates a new WindowItem and assigns the same
+WindowObject to it. Finally, for secondary WindowItems, there's also a \uicontrol P button on the
+right of the title bar that sets the \l{WindowItem::primary}{primary} property of that WindowItem
+to true.
 
-This example shows that it is possible to assign the same WindowObject to multiple WindowItems (so that
-you get the same surface being rendered multiple times on the screen) and the difference between being
-a primary WindowItem or not. Its implementation builds on top of the \l{Animated Windows System-UI Example}.
-
-The button on the top left of the screen shows the icon (a cog) of the only built-in application of this
-example. Overlayed on the icon is the action taken when you click on it. "Start" will be shown when the
-application is not running, and clicking on it will call \l{ApplicationObject::start}{ApplicationObject.start}.
-Otherwise it will show "Stop" and the corresponding action will be executed when clicked.
-
-Once the application is started, its sole window will be shown, decorated with a title bar and borders.
-The title bar displays "Primary" if \l{WindowItem::primary}{WindowItem.primary} is true or "Secondary"
-otherwise. Then comes the name of the application that created the window, which in this example is called
-simply "App1". On the far left of a window's title bar is a "-" button that destroys its WindowItem and on
-the far right a "+" button that creates a new WindowItem and assigns the same WindowObject to it. Finally,
-in case of secondary WindowItems, there will also be a "P" button on the right side of the title bar that
-sets the \l{WindowItem::primary}{primary} property of that WindowItem to true.
-
-The background color of the window turns red when pressed. So when you click over the \l{WindowItem::primary}{primary}
-WindowItem you will see that the event reaches the application since it sets the background color of its
-window to red. But if you create one or more secondary WindowItems and click on them you will notice that
-these secondary windows won't flash red, as secondary WindowItems do not forward input events to the WindowObjects they
-render.
+When you click on a window, its background color turns red. So when you click on the
+\l{WindowItem::primary}{primary} WindowItem you'll see that the event reaches the application,
+since the window's background color becomes red. But if you create one or more secondary
+WindowItems and click on them, you will notice that these secondary windows don't flash red, as
+secondary WindowItems do not forward input events to the WindowObjects they render.
 */
diff --git a/examples/applicationmanager/process-status/doc/src/process-status-example.qdoc b/examples/applicationmanager/process-status/doc/src/process-status-example.qdoc
index 78986d54..69d02cd7 100644
--- a/examples/applicationmanager/process-status/doc/src/process-status-example.qdoc
+++ b/examples/applicationmanager/process-status/doc/src/process-status-example.qdoc
@@ -29,26 +29,34 @@
 /*!
 
 \example applicationmanager/process-status
-\title Displaying Information About Application Processes
+\title Display Information about Application Processes
 \image process-status-example.png
 \brief How to use ProcessStatus to display application process information.
 \ingroup applicationmanager-examples
 
-This example shows you how to use the \l ProcessStatus component to display information
-about an application's process.
+\section1 Introduction
 
-This example is based on the simpler \l {"Hello World!" System-UI Example} {Hello World} one. You might
-want to start from there if you haven't seen it already.
+This example shows you how to use the \l ProcessStatus component to display information about
+an application's process. It is based on the simpler
+\l{"Hello World!" System UI Example}{Hello World}.
 
-On the left side the built-in applications are listed in a column, where each application has a row containing
-its icon and name next to a tabbed view that shows information about the application's process (in case the
-application is actually running).
+\b Prerequisites: You're already familiar with the concepts and topics introduced in the
+   \l {"Hello World!" System UI Example}.
 
-On the right side of the System-UI the windows of the running applications are stacked in a column, in order of
-appearance (oldest window at the top and youngest at the bottom).
+On the left, the built-in applications are listed in a column, where each application has a row
+that contains its icon and name, next to a tabbed view that shows information about the
+application's process (if the application is running).
 
-There are three applications available, a red one called "CPU Hog" which consumes a lot of CPU, a green one
-called "Memory Hog" that continually increases its memory consumption (so don't leave it running for too long
-as it will eat up all available RAM eventually) and a blue one called "Slim", which behaves normally.
+On the right of the System UI, the windows of the running applications are stacked in a column, in
+order of appearance: oldest window on top; youngest at the bottom.
+
+There are three applications available:
+
+\list
+    \li "CPU Hog" - a red application that consumes a lot of CPU
+    \li "Memory Hog" - a green application that continually increases its memory consumption;
+        don't leave it running for too long, it eats up all available RAM eventually.
+    \li "Slim" - a blue application that behaves normally.
+\endlist
 
 */