Doc: Reorganize parts of the documentation for better readability

* Rename "Overview Qt Remote Objects" to "Getting Started with Qt Remote Objects"
* Separate the 3 Examples into their own files so that they no longer require so much scrolling
* Fix some broken links due to the renaming

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

7 files changed, 449 insertions, 350 deletions

diff --git a/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc b/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc
index a01dd4e..5e5fe79 100644
--- a/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-cpp.qdoc
@@ -41,5 +41,5 @@
     \snippet snippets.pro project_file_include
 
 
-    For more information, see \l{Overview Qt Remote Objects}.
+    For more information, see \l{Getting Started with Qt Remote Objects}.
 */
diff --git a/src/remoteobjects/doc/src/remoteobjects-example-dynamic-replica.qdoc b/src/remoteobjects/doc/src/remoteobjects-example-dynamic-replica.qdoc
new file mode 100644
index 0000000..48b26e8
--- /dev/null
+++ b/src/remoteobjects/doc/src/remoteobjects-example-dynamic-replica.qdoc
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 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 remoteobjects-example-dynamic-replica.html
+\title Example 2: Direct Connection with a Dynamic Replica
+\brief Describes how the Qt Remote Objects establishes a direct connection with a dynamic replica.
+\target qtro-example2
+
+Initially, a dynamic replica is created as a "bare" QObject - without
+properties, signals or slots. Then, during initialization, QtRO returns the
+API for the object, after the connection to the source is made. Thus, the API
+is added to the object at runtime.
+
+There are no changes to be made on the source side, as a dynamic \l Replica
+only impacts how the requestor node acquires the replica. So, we use the
+source-side code shown in \l {qtro-example1}{Example 1}.
+
+\list 1
+    \li Add replica generation to the project.
+
+        Because the replica is dynamically acquired, no \c .rep file is
+        required unlike in \l {qtro-example1}{Example 1}.
+
+    \li Create the remote node and connect it to the source host node.
+
+        The code for this step is unchanged from \l {qtro-example1}{Example 1}.
+        \snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientnode_example2
+
+    \li Acquire a replica of the remote source object.
+
+        In \c main.cpp, we use a QSharedPointer to hold a replica of the
+        remote object, and then instantiate a replica requestor object:
+
+        \snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientmaincpp_example2
+\endlist
+
+The complete declaration and definition of the requestor class,
+\c DynamicClient, is as follows:
+
+\c dynamicclient.h
+\snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientheader_example2
+
+\c dynamicclient.cpp
+\snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientcpp_example2
+
+When run together with the source-side example, the output is identical
+to \l {qtro-example1}{Example 1}.
+
+*/
diff --git a/src/remoteobjects/doc/src/remoteobjects-example-registry.qdoc b/src/remoteobjects/doc/src/remoteobjects-example-registry.qdoc
new file mode 100644
index 0000000..7ffa295
--- /dev/null
+++ b/src/remoteobjects/doc/src/remoteobjects-example-registry.qdoc
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 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 remoteobjects-example-registry.html
+\title Example 3: Connections to Remote Nodes using a Registry
+\brief Describes how the Qt Remote Objects registry establishes connections between nodes.
+\target qtro-example3
+
+This example illustrates the use of a \l {Registry} to build the node topology.
+For simple networks, we use a QUrl to create a direct connection between two
+nodes. For complex networks, we use a registry, where you use a different QUrl
+to point both the host and replica nodes to the registry. For only two nodes,
+the benefits of using a registry are minimal. But, as the network grows, using
+a registry means that all nodes only need to connect to the registry via a single
+QUrl. In comparison, with direct connections, nodes would have to maintain a
+list of QUrls for every single node that they link to.
+
+\section2 Set up the Source
+
+The \c simpleswitch.h and \c simpleswitch.cpp sources from \l {qtro-example1}
+{Example} can be used without modification. The difference is in the way a host
+node is created and connected to the registry:
+
+\c main.cpp
+\snippet doc_src_simpleswitch.cpp simpleSwitch_registrymaincpp_example3
+
+\section2 Set up the Replica
+
+The requestor object used for this example is the dynamic replica client
+discussed in \l {qtro-example2}{Example 2}.
+
+The only modification is in \c main.cpp: a \l {Registry} node is created
+to acquire a \l {Replica}:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_registrydynamicclientmaincpp_example3
+
+When run together with the source-side example, the output is identical
+to \l {qtro-example1}{Example 1}.
+
+*/
diff --git a/src/remoteobjects/doc/src/remoteobjects-example-static-source.qdoc b/src/remoteobjects/doc/src/remoteobjects-example-static-source.qdoc
new file mode 100644
index 0000000..81be701
--- /dev/null
+++ b/src/remoteobjects/doc/src/remoteobjects-example-static-source.qdoc
@@ -0,0 +1,190 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 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 remoteobjects-example-static-source
+\title Example 1: Direct Connection using a Static Source
+\brief Describes how the Qt Remote Objects establishes a direct connection using a static source.
+\target qtro-example1
+
+In this example, the source object is a simple binary switch that toggles its
+state based on a timer. When the state changes, a signal is emitted by the
+source which QtRO propagates to all replicas. Since the replicas have the same
+properties, signals, and slots as were exposed from the source, any slots
+connected to the replica's signal will be called when the replica receives that
+signal. The client process then echoes back the received switch state to the
+source by emitting its own signal which is connected to a slot on the replica.
+
+\list 1
+\li \b {Create a source object}
+
+To create this \l Source object, first we create the definition file,
+\c simpleswitch.rep. This file describes the properties and methods for the
+object and is input to the Qt Remote Objects Compiler \l{repc}. This file only
+defines interfaces that are necessary to expose to the \l{Replica}{Replicas}.
+
+\c simpleswitch.rep
+\snippet doc_src_simpleswitch.cpp simpleSwitch_rep
+
+In \c simpleswitch.rep,
+\list
+    \li \c currState holds the current state of the switch.
+    \li \c server_slot() allows us to interact with the source - it will be
+        connected to the \c echoSwitchState(bool newstate) signal.
+\endlist
+
+For repc to process this file, add the following line to your \c .pro file:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_repsource_example1
+
+The \c REPC_SOURCE variable is only relevant for the Qt Remote Object module,
+so you need to add it to your project as well:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_remoteobjectsadd_example1
+
+repc creates the \c rep_SimpleSwitch_source.h header in the build directory
+that you specify. For more information, see \l{Source}.
+
+repc creates three helper classes for use with QtRO. For this example, we
+use the basic: \c SimpleSwitchSimpleSource. It's an abstract class, defined in
+\c rep_SimpleSwitch_source.h. We derive from it to define our SimpleSwitch
+implementation class as shown below:
+
+\c simpleswitch.h
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_serverheader_example1
+
+In \c simpleswitch.h,
+\list
+    \li \c stateChangeTimer is a QTimer that is used to toggle the state of our
+        SimpleSwitch.
+    \li \c timeout_slot() is connected to \c stateChangeTimer's timeout() signal.
+    \li \c server_slot() -- which is called automatically on the source whenever
+        any replica calls their version of the slot -- outputs the received value.
+    \li \c currStateChanged(bool), defined in the \l{repc}-generated
+        \c rep_SimpleSwitch_source.h, is emitted whenever \c currState toggles.
+        In this example, we ignore the signal on the source side, and handle it
+        later on the replica side.
+\endlist
+
+The definition of our \c SwitchState class is shown below:
+
+\c simpleswitch.cpp
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_serversource_example1
+
+\li \b {Create a registry}
+
+Because this example uses a direct connection between nodes, we can omit this
+step.
+
+\li \b {Create a host node}
+
+The host node is created as shown below:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_serverhostnode_example1
+
+\li \b {Host source object and remoting}
+
+The following statements instantiate the \l {Source} object and pass it on to
+the host to enable "remoting", which is the process of making an object visible
+to the QtRO network:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_enableremoting_example1
+
+The contents of \c main.cpp file that implements the steps described above are
+as follows:
+
+\c main.cpp
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_servermaincpp_example1
+
+Compile and run this source-side project. The output, without any replicas
+created, should look as shown below with the switch state toggling between
+\c true and \c false every two seconds.
+
+\image DirectConnectServerOutput.png "Example 1: Server Output"
+
+\endlist
+
+The subsequent steps are for creating the replica side of the network, which in
+this example gets the state of switch from the \l {Source} and echoes it back.
+
+\section2 Replica Code
+
+\list 1
+\li \b {Use repc to add a replica to your project}
+
+We use the same API definition file as we did on the source side,
+\c SimpleSwitch.rep, to create a \l {Replica} header file using the \l {repc}.
+Include the following line in your client side \c .pro file, specifying a
+\c .rep file input:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_clientrep_example1
+
+The \l {repc} tool generates a \c rep_SimpleSwitch_replica.h file in the build
+directory. For more information, see \l{Replica}.
+
+\li \b {Create a node to connect with the source's host node}
+
+The following code instantiates the second node on the network and connects it
+with the source host node:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_clientremotenode_example1
+
+\li \b {Call the node's \l{QRemoteObjectNode::}{acquire()} to create a pointer
+    to a replica}
+
+First, we instantiate a replica:
+
+\snippet doc_src_simpleswitch.cpp simpleSwitch_clientacquirereplica_example1
+
+\note \l{QRemoteObjectNode::}{acquire()} returns a pointer to the replica, but
+doesn't manage its lifetime. This example shows the recommended process of
+wrapping the returned pointer in a QSharedPointer or QScopedPointer to ensure
+that the pointer is always deleted properly.
+
+\c main.cpp implements the steps described above and instantiates our object:
+
+\c main.cpp
+\snippet doc_src_simpleswitch.cpp simpleSwitch_clientmain_example1
+
+The complete declaration and definition for the \c Client class is as follows:
+
+\c client.h
+\snippet doc_src_simpleswitch.cpp simpleSwitch_clientheader_example1
+
+\c client.cpp
+\snippet doc_src_simpleswitch.cpp simpleSwitch_clientcpp_example1
+
+Compiling and running this example together with the source-side example
+generates the following output:
+
+\image DirectConnectClientServerOutput.png "Direct Connect Server Client Communication output"
+\endlist
+
+*/
diff --git a/src/remoteobjects/doc/src/remoteobjects-gettingstarted.qdoc b/src/remoteobjects/doc/src/remoteobjects-gettingstarted.qdoc
new file mode 100644
index 0000000..f4bec3f
--- /dev/null
+++ b/src/remoteobjects/doc/src/remoteobjects-gettingstarted.qdoc
@@ -0,0 +1,117 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 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-gettingstarted.html
+\title Getting Started with Qt Remote Objects
+\brief Detailed information on how to use Qt Remote Objects.
+
+\section1 Introduction
+
+The Qt Remote Objects module provides an easy way to share Qt APIs between
+processes and devices. For this to work, we require a data channel between
+processes and devices. To establish this data channel, first, you need a
+QRemoteObjectNode.
+
+In QtRO, a node is an endpoint for communication. In a remote objects network,
+each participant, be it a process or a device, needs its own node. QtRO is a
+peer-to-peer network, with connected nodes being the links in the network.
+
+Nodes, by themselves, don’t provide much use. But their value comes when you
+add QObject classes to a node to share. Then, any peer node can request a copy
+or instance of the shared object from the \e{host node}, the node that shares
+it.
+
+Unlike when using normal class instances (with independent properties and
+signal emissions), QtRO automatically synchronizes changes to the shared object
+across all of its copies. With a few exceptions, these copies have the
+identical Qt API as the original object, and are meant to be used exactly as if
+the original object were available.
+
+In QtRO, the original object is called the \l{Source}. It's a fully-implemented
+C++ class, with the necessary business logic to provide the required
+functionality. Copies of this object are called \l{Replica}s. You don’t need
+to write any C++ code for a replica; you request an instance from a node
+instead. While you do need some code to use the replica, such as connecting
+signals to your own slots, you don’t need to implement the internal behavior –
+that's already done for you in the source.
+
+Because the source can be in a different process or even on a different device,
+there are factors in QtRO that you need to consider, which you typically
+wouldn't run into when developing without Inter-Process Communication (IPC).
+Specifically, what happens if the process or device isn't there? This is where
+the additions to the Replica API come in:
+
+\list
+    \li The \l{QRemoteObjectReplica::}{initialized()} signal is emitted once the
+        replica has received the \l{Source}{source} state from the QtRO
+        network.
+    \li Both the \l{QRemoteObjectReplica::}{isReplicaValid} property and the
+        \l{QRemoteObjectReplica::}{stateChanged()} signal alert you if the
+        connection is lost.
+\endlist
+
+Objects shared over QtRO use the links (conduits) between nodes for all
+communication. If you want to share a QObject, you must create a \e{host node}
+with a URL other nodes can connect to. You can also use the \l{Registry} to
+facilitate connections, but your nodes that share \l{Source}{sources} still need
+to be host nodes. Each shared object is given a name (a QString), used to
+identify it on the QtRO network.
+
+\section1 Implementation
+
+To illustrate the use of remote objects, on the source side, we need to:
+
+\list 1
+    \li Create the \l {Source} object that is replicated to other nodes, with or
+        without using \l repc, the Qt Remote Objects Compiler.
+    \li Optionally, create the \l{Registry}. Otherwise, use direct connections.
+    \li Create a host node so that the source object can be shared.
+    \li Call the node's \l{QRemoteObjectHostBase::}{enableRemoting()} function
+        to share the source object.
+\endlist
+
+On the replica side, we need to:
+
+\list 1
+    \li Optionally, use \l repc to generate a \l{Replica} header for your project.
+    \li Create the node that will connect with the \l{Source} host node.
+    \li Call the node's \l{QRemoteObjectNode::}{acquire()} function to create a
+        pointer to a replica.
+\endlist
+
+The following examples illustrate both \l{repc}-compiled static objects and dynamic
+source objects. Additionally, they also show direct connections as well as
+connections that use a \l{Registry} between nodes.
+
+\list
+    \li \l{Example 1: Direct Connection using a Static Source}
+    \li \l{Example 2: Direct Connection with a Dynamic Replica}
+    \li \l{Example 3: Connections to Remote Nodes using a Registry}
+\endlist
+
+*/
diff --git a/src/remoteobjects/doc/src/remoteobjects-index.qdoc b/src/remoteobjects/doc/src/remoteobjects-index.qdoc
index c982019..4c63a41 100644
--- a/src/remoteobjects/doc/src/remoteobjects-index.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-index.qdoc
@@ -111,7 +111,7 @@ Consider a service that provides access to a printer. In QtRO terms:
 
 \section1 Guides
  \list
-    \li \l {Overview Qt Remote Objects}
+    \li \l {Getting Started with 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}
diff --git a/src/remoteobjects/doc/src/remoteobjects-overview.qdoc b/src/remoteobjects/doc/src/remoteobjects-overview.qdoc
deleted file mode 100644
index 75cb5f4..0000000
--- a/src/remoteobjects/doc/src/remoteobjects-overview.qdoc
+++ /dev/null
@@ -1,348 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 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-gettingstarted.html
-\title Overview Qt Remote Objects
-\brief Introduction to using Qt Remote Objects.
-\ingroup overviews
-
-
-\section1 Introduction
-
-The \e {Qt Remote Objects} (QtRO) module provides an easy way to share Qt APIs
-between processes and devices. A data channel between processes and devices is
-required for this to work. Therefore, the first thing you need in QtRO is a
-QRemoteObjectNode. In QtRO, a node is an endpoint for communication. Each
-participant in a remote objects network, be it a process or a device, needs
-its own node. QtRO is a peer-to-peer network, with connected nodes being the
-links in the network.
-
-Nodes, by themselves, don’t provide much use. The value comes from adding
-QObject classes to a node for sharing. Any peer node can then request a
-copy/instance of the shared object from the node that shares it (called the
-\e {host node}). Unlike when using normal class instances (with independent
-properties and signal emissions), the idea in QtRO is to synchronize the
-changes of the shared object to all of the copies. With a few exceptions, the
-copies have the exact same Qt API as the original object, and are intended to
-be used exactly as if the original object were available. In QtRO, the
-original object is called the \l {Source}. It is a fully implemented C++
-class, with whatever business logic is needed to provide the desired
-functionality. Copies of this object are called \l {Replica}s. You don’t need
-to write any C++ code for a replica; instead, you simply request an
-instance from a node. You still need some code to use it, such as connecting
-signals to your own slots, but you don’t need to implement the internal
-behavior – that was already done in the source object.
-
-Because the source can be in a different process or even on a different
-device, there are concerns in QtRO that you won’t run into when developing
-without Inter-Process Communication (IPC). Specifically, what happens if the
-process or device isn’t there? This is where the additions to the \l Replica
-API come in. There is an \l {QRemoteObjectReplica::}{initialized()} signal
-that is emitted once the replica has received the \l {Source}{source} state
-from the QtRO network. There is also an \l {QRemoteObjectReplica::}
-{isReplicaValid} property and a \l {QRemoteObjectReplica::}{stateChanged()}
-signal to alert you if the connection is lost.
-
-Objects shared over QtRO use the links (conduits) between nodes for all
-communication. If you intend to share a QObject, you must create a \e {host
-node} with a URL other nodes can connect to. You can also use the QtRO \l
-{Registry} to facilitate connections, but your nodes sharing \l {Source}
-{sources} still need to be Host nodes. Each shared object is given a name
-(a QString), used for identifying it on the QtRO network.
-
-See the \l {Qt Remote Objects} {Overview} for a more detailed description, or
-use the following examples to get started with QtRO.
-
-\section1 Implementation
-
-To illustrate the use of remote objects, on the source side we need to:
-
-\list 1
-    \li Create the \l {Source} object that will be replicated to other nodes
-       (with or without using \l repc, the Qt Remote Objects Compiler).
-    \li (Optional) Create the \l {Registry}. If not used, direct connections
-        are required.
-    \li Create a host node so the source object can be shared.
-    \li Call the node's \l {QRemoteObjectHostBase::}{enableRemoting()}
-        function to share the source object.
-\endlist
-
-And on the replica side:
-
-\list 1
-    \li (Optional) Use \l repc to generate a \l {Replica} header for your
-        project.
-    \li Create the node that will connect with the \l {Source} host node.
-    \li Call the node's \l {QRemoteObjectNode::}{acquire()} function to create
-        a pointer to a replica.
-\endlist
-
-The examples below will show both \l {repc}-compiled static objects and
-dynamic source objects. The examples will also show direct connections as
-well as connections using a \l {Registry} between nodes.
-
-\target qtro-example1
-\section1 Example 1: Direct Connection Using a Static Source
-
-In this example, the source object is a simple binary switch that will
-toggle its state based on a timer. When the state changes, a signal is
-emitted by the source which QtRO propagates to all replicas. As the replica
-will have the same properties, signals and slots as were exposed from the
-source object, any slots connected to the replica's signal will be called when
-the replica receives the signal. The client process then echoes back the
-received switch state to the source by emitting its own signal which is
-connected to a slot on the replica.
-
-\list 1
-\li \b {Create a source object}
-
-To create this \l Source object, we first create the definition file,
-\c simpleswitch.rep. This file describes the properties and methods for the
-object and is input to the \l {repc} utility which is part of Qt Remote
-Objects. Only the interfaces that need to be exposed to \l {Replica}
-objects are defined in this file.
-
-\c simpleswitch.rep
-\snippet doc_src_simpleswitch.cpp simpleSwitch_rep
-
-Above,
-\list
-    \li \c currState holds the current state of the switch, and
-    \li \c server_slot() allows us to interact with the \l {Source} - it
-        will be connected to the \c echoSwitchState(bool newstate) signal.
-\endlist
-
-For \l {repc} to process this file, add the following line to the \c .pro
-file:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_repsource_example1
-
-The \c REPC_SOURCE variable is only relevant for the Qt Remote Object
-module, so you need to add it to your project as well:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_remoteobjectsadd_example1
-
-\l {repc} creates the header \c rep_SimpleSwitch_source.h in your specified
-build directory. Refer to the \l {Source} section for more details about this
-file.
-
-Repc creates three helper classes for use with QtRO. For this example, we
-will use the most basic: \c SimpleSwitchSimpleSource. It is an abstract
-class, defined in \c rep_SimpleSwitch_source.h. We derive from it to
-define our SimpleSwitch implementation class as shown below:
-
-\c simpleswitch.h
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_serverheader_example1
-
-Above,
-\list
-    \li \c stateChangeTimer is a QTimer that is used to toggle the state of
-        our SimpleSwitch,
-    \li \c timeout_slot() is connected to the timeout() signal of
-        \c stateChangeTimer,
-    \li \c server_slot() -- which is called on the source (automatically
-        via QtRO) whenever any replica calls their version of the slot --
-        outputs the received value, and
-    \li \c currStateChanged(bool), defined in \l {repc}-generated
-        \c rep_SimpleSwitch_source.h, is emitted whenever currState
-        toggles. In this example, we ignore the signal on the source side,
-        and handle it later on the replica side.
-\endlist
-
-The definition of our \c SwitchState class is shown below:
-
-\c simpleswitch.cpp
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_serversource_example1
-
-\li \b {Create a registry}
-
-Because this example involves using a direct connection between nodes,
-step 2 for \l {Registry} creation is omitted.
-
-\li \b {Create a host node}
-
-The host node is created as shown below:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_serverhostnode_example1
-
-\li \b {Host source object and remoting}
-
-The following statements instantiate the \l {Source} object and pass it to
-the host to enable "remoting", that is, making the object visible to the QtRO
-network:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_enableremoting_example1
-
-The contents of \c main.cpp file that implements the above steps are shown
-below:
-
-\c main.cpp
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_servermaincpp_example1
-
-Compile and run this (source side) project. The output (without any replicas
-created) should look as shown below with the switch state toggling between \c
-true and \c false every two seconds.
-
-\image DirectConnectServerOutput.png "Example 1: Server output"
-
-Next are the steps for creating the replica side of the network, which in this
-example gets the state of switch from the \l {Source} and echoes it back.
-\endlist
-
-\section2 Replica Code
-
-\list 1
-\li \b {Use repc to add a replica to your project}
-
-The same API definition file as was used on the source side,
-\c SimpleSwitch.rep, is used for creating a \l {Replica} header file using
-the \l {repc} utility. Include the following line in your client side \c .pro
-file, specifying a \c .rep file input:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_clientrep_example1
-
-The \l {repc} tool generates a \c rep_SimpleSwitch_replica.h file in the build
-directory. Refer to \l {Replica} section for more details about this file.
-
-\li \b {Create a node to connect with the source's host node}
-
-The following code instantiates the second node on the network and connects it
-with the source host node:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_clientremotenode_example1
-
-\li \b {Call node's \l {QRemoteObjectNode::}{acquire()} to create a pointer
-    to a replica}
-
-First, a replica is instantiated:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_clientacquirereplica_example1
-
-Note that \l {QRemoteObjectNode::}{acquire()} returns a pointer to the
-replica. However, it does not manage the pointer lifetime. This example uses
-the recommended process of wrapping the returned pointer in a QSharedPointer
-or QScopedPointer to ensure the pointer is properly deleted.
-
-\c main.cpp implements above steps and instantiates our object:
-
-\c main.cpp
-\snippet doc_src_simpleswitch.cpp simpleSwitch_clientmain_example1
-
-Complete declaration and definition of the \c Client class:
-
-\c client.h
-\snippet doc_src_simpleswitch.cpp simpleSwitch_clientheader_example1
-
-\c client.cpp
-\snippet doc_src_simpleswitch.cpp simpleSwitch_clientcpp_example1
-
-Compiling and executing this example together with the source-side example
-generates the following output:
-
-\image DirectConnectClientServerOutput.png "Direct Connect Server Client Communication output"
-\endlist
-
-\target qtro-example2
-\section1 Example 2: Direct Connection with a Dynamic Replica
-
-A dynamic replica is initially created as a "bare" QObject - that is, it has
-no properties, signals or slots. QtRO returns the API for the object during
-initialization (after the connection to the source is made), thus the API is
-added to the object at runtime.
-
-There are no changes to the source side as a dynamic \l Replica only impacts
-how the requestor node acquires the replica. The source-side code shown
-in \l {qtro-example1}{Example 1} will be used.
-
-\list 1
-    \li Add replica generation to project.
-
-        Because the replica is dynamically acquired, no \c .rep file is
-        required unlike in \l {qtro-example1}{Example 1}.
-
-    \li Create the remote node and connect it with the source host node.
-
-        The code for this step is unchanged from \l {qtro-example1}{Example 1}.
-        \snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientnode_example2
-
-    \li Acquire a replica of the remote source object.
-
-        In \c main.cpp, we use a QSharedPointer to hold a replica of the
-        remote object, and then instantiate a replica requestor object:
-
-        \snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientmaincpp_example2
-\endlist
-
-Below is the complete declaration and definition of the requestor class
-(\c DynamicClient in this example):
-
-\c dynamicclient.h
-\snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientheader_example2
-
-\c dynamicclient.cpp
-\snippet doc_src_simpleswitch.cpp simpleSwitch_dynamicclientcpp_example2
-
-When executed together with the source-side example, the output is identical
-to \l {qtro-example1}{Example 1}.
-
-\target qtro-example3
-\section1 Example 3: Remote Nodes using a Registry
-
-This example will illustrate the use of a \l {Registry} for building the node
-topology. For only two nodes, the benefits of using a registry are minimal.
-With a registry, instead of using a QUrl to create a direct connection between
-two nodes, you use a different QUrl to point both the host and replica nodes to
-the registry. As the network grows, using a registry means that all nodes only
-need to connect to the registry via a single QUrl. With direct connections,
-nodes would have to maintain a list of \l {QUrl}s for each node they link to.
-
-\section2 Source Code
-
-The \c simpleswitch.h and \c simpleswitch.cpp sources from \l {qtro-example1}
-{Example} can be used without modification. The difference is in the way a host
-node is created and connected to the \l {Registry}:
-
-\c main.cpp
-\snippet doc_src_simpleswitch.cpp simpleSwitch_registrymaincpp_example3
-
-\section2 Replica Code
-
-The requestor object used for this example is the dynamic replica client
-discussed in \l {qtro-example2}{Example 2}.
-
-The only modification is in \c main.cpp: a \l {Registry} node is created
-to acquire a \l {Replica}:
-
-\snippet doc_src_simpleswitch.cpp simpleSwitch_registrydynamicclientmaincpp_example3
-
-When executed together with the source-side example, the output is identical
-to \l {qtro-example1}{Example 1}.
-*/