doc: Expand the overview docs of Qt Wayland Compositor

There is some confusion with regards to what types of features
the Wayland Compositor provides and how it related to
application managers. This tries to expand the entry point
description in the docs to give a more detailed description.

Change-Id: I96f58c04646c69575a1bd4e4b9178c5722d752d6
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Johan Helsing <johan.helsing@qt.io>

1 files changed, 52 insertions, 4 deletions

diff --git a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
index 05ab4fb03..d2fb6a27d 100644
--- a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
+++ b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
@@ -30,10 +30,58 @@
   \title Qt Wayland Compositor
   \brief An API to develop display servers supporting the Wayland protocol
 
-  Qt Wayland Compositor is a module that provides QML and C++ APIs for
-  developing custom display servers based on the
-  \l{http://wayland.freedesktop.org}{Wayland protocol}. The server displays
-  content from client applications that support the Wayland protocol.
+  \l {https://wayland.freedesktop.org/} {Wayland} is a display server
+  protocol to help in creating multi-process systems, where multiple client
+  applications may render content on the same display, by going via
+  a compositor process.
+
+  Compared to a system with a single-process design, a multi-process system
+  gives several benefits:
+
+  \list
+  \li Easier resource management, through the regular operating system mechanisms.
+  \li Better security, as each application can run with its own permissions or
+      sandbox.
+  \li Clearer separation of application UI and compositor UI, so each
+      can be modified independently.
+  \endlist
+
+  In a typical Wayland-based system, multiple client processes will render their
+  own contents to off-screen buffers. The information about these buffers will
+  then be passed to a display server process by using the Wayland protocol.
+  Finally, the display server process will composite and position the contents
+  on a physical display.
+
+  Qt Wayland Compositor is a module that provides convenient and powerful
+  QML and C++ APIs for developing custom display servers based on this protocol.
+  The server displays content from client applications that support the Wayland
+  protocol. The design philosophy of Wayland is to keep the core protocol simple
+  and minimal, and to expand on this with use-case-specific extensions. Qt Wayland
+  Compositor supports many common extensions by default, and also has APIs that
+  enables the creation of new, custom extensions.
+
+  In one typical use case, a display server written with Qt Wayland Compositor will
+  be a subsystem inside a larger application manager process. Qt Wayland Compositor
+  provides the APIs to communicate with clients and display their contents on screen,
+  using C++ for low-level access and the full set of Qt Quick effects, animations and
+  convenience when using the QML APIs. A typical application manager would, in addition
+  to this, implement features such as application life cycle, virtual keyboard input,
+  security and IPC. Qt provides APIs that can be used to develop the remaining parts
+  of an application manager in other modules. The \l {https://www.qt.io/qt-automotive-suite/}
+  {Qt Automotive Suite} provides a complete application manager which includes a
+  display server developed using Qt Wayland Compositor.
+
+  \section1 Features of Qt Wayland Compositor
+
+  The Qt Wayland Compositor API includes features needed to create a display server.
+
+  \list
+  \li A QML API that can be used to display and manipulate client content, fully
+      integrated with all the features in Qt Quick.
+  \li A C++ API for low-level access and control.
+  \li Support for common extensions, including XDG Shell and IVI Application.
+  \li APIs to easily expand support to include custom extensions.
+  \endlist
 
   \section1 Environment Variables and Command-line Arguments