Doc: Improve the documentation landing page

* Merge the use cases into a more prominent location: the landing page, so that the reader
   has a better chance of visualizing how to use the module in real-life use cases.
* Update the C++ Reference module documentation to suit other Qt modules.
* Removed the include statements from the landing page as that's only for C++ and this
   module also provides QML.
* Reduce the number of links to "Source" and "Replica" as we don't have to link to every
   single instance.

Change-Id: Ic227cd7adcc25fc9d3bfdf3e2239d62403b36bba
Reviewed-by: Michael Brasser <michael.brasser@live.com>

4 files changed, 48 insertions, 73 deletions

diff --git a/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc b/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc
index 3785901..a01dd4e 100644
--- a/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc
@@ -28,15 +28,18 @@
 /*!
 \module QtRemoteObjects
 \title Qt Remote Objects C++ Classes
-\brief The Qt Remote Objects module provides an easy to use mechanism for sharing a QObject (Properties/Signals/Slots) between processes.
+\brief Provides an easy to use mechanism for sharing a QObject's Properties, Signals, or Slots, between processes.
 \ingroup modules
 \qtvariable remoteobjects
 
-    To use Qt Remote Objects in your application, add the following configuration option to your \c .pro file:
-    \snippet snippets.pro project_file_include
+    To include the definitions of the module's classes, use the following directive:
 
-    Use the following include in you source files:
     \snippet doc_src_remoteobjects.h qtremoteobject_include
 
-    See \l{Overview Qt Remote Objects} for an introduction to the module.
+    To link against the module, add this line to your qmake \c{.pro} file:
+
+    \snippet snippets.pro project_file_include
+
+
+    For more information, see \l{Overview Qt Remote Objects}.
 */
diff --git a/src/remoteobjects/doc/src/remoteobjects-index.qdoc b/src/remoteobjects/doc/src/remoteobjects-index.qdoc
index d1bb45d..c982019 100644
--- a/src/remoteobjects/doc/src/remoteobjects-index.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-index.qdoc
@@ -71,24 +71,47 @@ creating it yourself, possibly use the status signals
 (\l {QRemoteObjectReplica::} {isReplicaValid()}), but then interact with the
 object like you would with any other QObject-based type.
 
-\section1 Get Started
+\section1 Use Case: GPS
 
-To enable \e {Qt Remote Objects} in a project, add this directive into
-the C++ files:
+Consider a sensor such as a Global Positioning System (GPS) receiver. In
+QtRO terms:
 
-\code
-#include <QtRemoteObjects>
-\endcode
+\list
+    \li The \l{Source} would be the process that directly interacts with the
+        GPS hardware and derives your current location.
+    \li The location would be exposed as QObject properties; the periodic
+        updates to the location would update these properties and emit property
+        changed signals.
+    \li \l{Replica}{Replicas} would be created in other processes and would
+        always know your current location, but wouldn't need any of the logic
+        to compute the location from the sensor data.
+    \li Connecting to the location changed signal on the Replica would work as
+        expected: the signal emitted from the Source would trigger the signal
+        emission on every Replica.
+\endlist
+
+\section1 Use Case: Printer Access
+
+Consider a service that provides access to a printer. In QtRO terms:
 
-To link against the \e {Qt Remote Objects} module, add this line to the project file:
-\code
-QT += remoteobjects
-\endcode
+\list
+    \li The \l{Source} would be the process controlling the printer directly.
+    \li The ink levels and printer status would be monitored by QObject
+        properties. Updates to these properties would emit property changed
+        signals.
+    \li The key feature -- being able to print something -- needs to be passed
+        back to the printer. Incidentally, this aligns with the Qt slot mechanism,
+        which QtRO uses as the way for \l{Replica}{Replicas} to make calls on the
+        Source. In effect, properties and signals go from Source to Replicas;
+        slots go from Replica to Source.
+    \li When a print request is accepted, the printer status would change,
+        triggering a change in the status property. This would then be reported
+        to all Replicas.
+\endlist
 
 \section1 Guides
  \list
     \li \l {Overview Qt Remote Objects}
-    \li \l {Using Qt Remote Objects}
     \li \l {Qt Remote Objects Nodes}
     \li \l {Source Objects}{Qt Remote Objects Source Objects}
     \li \l {Replica Objects}{Qt Remote Objects Replica Objects}
@@ -102,8 +125,10 @@ QT += remoteobjects
 
 \section2 Reference
 
-\l {Qt Remote Objects C++ Classes}
-\l {Qt Remote Objects QML Types}
+\list
+    \li \l {Qt Remote Objects C++ Classes}
+    \li \l {Qt Remote Objects QML Types}
+\endlist
 
 \section1 Licenses
 
diff --git a/src/remoteobjects/doc/src/remoteobjects-use.qdoc b/src/remoteobjects/doc/src/remoteobjects-use.qdoc
deleted file mode 100644
index fd375ca..0000000
--- a/src/remoteobjects/doc/src/remoteobjects-use.qdoc
+++ /dev/null
@@ -1,53 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2018 Ford Motor Company
-** Contact: https://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 https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-/*!
-\page qtremoteobjects-use.html
-\title Using Qt Remote Objects
-\brief Introduction to using Qt Remote Objects.
-
-Consider a sensor; a global positioning system (GPS) receiver for instance. In
-QtRO terms, the \l {Source} would be the process that directly interacts with
-the GPS hardware and derives your current location. The location would be
-exposed as QObject properties, and the periodic updates to the location would
-update the properties and emit property changed signals. \l {Replica}s would be
-created in other processes and would always know your current location, but
-would not need any of the logic to compute the location from the sensor data.
-Connecting to the location changed signal on the \l {Replica} would work as
-expected, as the signal emitted from the \l {Source} would trigger the signal
-emission on every \l {Replica}.
-
-Another example of QtRO usage would be for a service (for example, access to a printer).
-The \l {Source} is again the process controlling the printer directly. Here you
-would again likely have properties monitoring the ink levels or whether the printer is
-currently busy. However, the key feature, being able to print something, needs to be
-passed back to the printer. This aligns with the Qt slot mechanism, which QtRO
-uses as the way for \l {Replica}s to make calls on the \l {Source}. In effect,
-properties and signals go from \l {Source} to \l {Replica}s, while slots go
-from (a) \l {Replica} to the \l {Source}. Assuming a print request is accepted,
-the printer status would change, which would change the status property. This
-would then be reported to all \l {Replica}s.
-*/
diff --git a/src/remoteobjects/qconnectionfactories.cpp b/src/remoteobjects/qconnectionfactories.cpp
index f1091fa..0742eb5 100644
--- a/src/remoteobjects/qconnectionfactories.cpp
+++ b/src/remoteobjects/qconnectionfactories.cpp
@@ -264,7 +264,7 @@ QString ExternalIoDevice::deviceType() const
 /*!
     \class QtROServerFactory
     \inmodule QtRemoteObjects
-    \brief A class holding information about server backends available on the Qt Remote Objects network.
+    \brief A class that holds information about server backends available on the Qt Remote Objects network.
 */
 QtROServerFactory::QtROServerFactory()
 {
@@ -283,7 +283,7 @@ QtROServerFactory *QtROServerFactory::instance()
 /*!
     \class QtROClientFactory
     \inmodule QtRemoteObjects
-    \brief A class holding information about client backends available on the Qt Remote Objects network.
+    \brief A class that holds information about client backends available on the Qt Remote Objects network.
 */
 QtROClientFactory::QtROClientFactory()
 {