doc: Review Replica and Interaction topics

* Minor fixes throughout these two topics to match the earlier patches
* Update the link on the index page so it won't break

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

3 files changed, 75 insertions, 73 deletions

diff --git a/src/remoteobjects/doc/src/remoteobjects-index.qdoc b/src/remoteobjects/doc/src/remoteobjects-index.qdoc
index e6e50d4..00ae210 100644
--- a/src/remoteobjects/doc/src/remoteobjects-index.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-index.qdoc
@@ -114,7 +114,7 @@ Consider a service that provides access to a printer. In QtRO terms:
     \li \l {Getting Started with Qt Remote Objects}
     \li \l {Qt Remote Objects Nodes}{Nodes}
     \li \l {Qt Remote Objects Source}{Sources}
-    \li \l {Qt Remote Objects Replica Objects}{Replicas}
+    \li \l {Qt Remote Objects Replica}{Replicas}
     \li \l {Qt Remote Objects Registry}{Registry}
     \li \l {Qt Remote Objects - External QIODevices}{External QIODevices}
     \li \l {Qt Remote Objects Compiler}{Compiler}
diff --git a/src/remoteobjects/doc/src/remoteobjects-interaction.qdoc b/src/remoteobjects/doc/src/remoteobjects-interaction.qdoc
index 6af7efe..003c8a4 100644
--- a/src/remoteobjects/doc/src/remoteobjects-interaction.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-interaction.qdoc
@@ -26,23 +26,25 @@
 ****************************************************************************/
 /*!
 \page qtremoteobjects-interaction.html
-\brief Describes how source/replica interaction works.
+\brief Describes how a source and replicas interact with one another.
 \section1 Remote Object Interaction
 
-Source/replica interaction is directional. Property changes and signal emission
-happen on the source, and are propagated to all replicas. If a property is
-writable, you can call the setter function on a replica. This will be forwarded
-to the source, and if a change is made, it will be made on the source and
-subsequently forwarded to all replicas. To the replica, it is then an
-asynchronous call, with latency before the change takes effect.
+The interaction between source and replicas is directional. Property changes
+and signal emission happen on the source, and are propagated to all replicas.
+If a property is writable, you can call the setter function on a replica, which
+is then forwarded to the source. Afterwards, if this call results in a new
+property value, that value is first changed at the source and then subsequently
+forwarded to all replicas. To the replica, it is then an asynchronous call,
+with latency before the change takes effect.
 
-While technically you can emit a signal on a replica, this may have unexpected results and
-is discouraged for that reason. It will only trigger slots connected to the
-replica itself, not slots connected to the source or other replicas. Like
-property setters, slot invocations on a replica are forwarded to the Source to
+While technically you can emit a signal on a replica, this is discouraged as it
+may have unexpected results. It will only trigger slots connected to the
+replica itself; not slots connected to the source or other replicas. Like
+property setters, slot invocations on a replica are forwarded to the source to
 run.
 
-The behavior above is implemented automatically by QtRO, there is no need to
-write any replica implementation code. It will be handled automatically at
-runtime for dynamic replicas, or at compile time for repc generated headers.
+Qt Remote Objects automatically implements the behavior described above. There
+is no need to write any replica implementation code. For dynamic replicas,
+this is handled automatically at runtime. For \l{repc} generated headers, this
+is handled at compile time.
 */
diff --git a/src/remoteobjects/doc/src/remoteobjects-replica.qdoc b/src/remoteobjects/doc/src/remoteobjects-replica.qdoc
index 4ed144b..e3aae81 100644
--- a/src/remoteobjects/doc/src/remoteobjects-replica.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-replica.qdoc
@@ -27,87 +27,87 @@
 /*!
 \page qtremoteobjects-replica.html
 \title Qt Remote Objects Replica
-\brief Describes how the remote object replica works as a surrogate object.
+\brief Describes the concept of a replica and how it works as a surrogate object.
 \target Replica
-\section1 Replica Objects
 
-A remote object replica is a surrogate object that has (approximately) the same API
-as the \l {Source} QObject it is replicating. There are a few additional
-properties and signals to make it possible to detect when the Replica is
-initialized or if it loses its connection to the \l {Source} object. There
-are a few other differences: a constant property on the source cannot
-be constant on the replica. The value will not be known at the time the
-replica is instantiated, it will only be known once the replica is initialized
-(see \l {Remote Object Interaction}).
+A QRemoteObjectReplica ("replica") is a surrogate object that has approximately
+the same API as the \l {Source} QObject it replicates. Additionally, there are
+a few properties and signals to make it possible to detect when the replica is
+initialized or if it loses its connection to the source object. There
+are a few other differences, notably, a constant property on the source cannot
+be constant on the replica. The value will not be known at the time when the
+replica is instantiated; it will only be known once the replica is initialized.
+For more information, see \l {Remote Object Interaction}.
 
 A compiled replica is a \l {QRemoteObjectReplica} based type, where the derived
-class definition is automatically generated by the \l {repc} compiler. Only a
-header file is generated (using the REPC_REPLICA variable in your .pro file
-will make generation part of the build process), but it is a complete type.
-There is no public constructor, you need to use the \l
-{QRemoteObjectNode::acquire} template function to create the Replica instance.
+class definition is automatically generated by the \l {repc} compiler. When you
+use the \c REPC_REPLICA variable in your \c{.pro} file, this makes the
+generation part of the build process. Although only a header is generated, it's
+a complete type. There is no public constructor, so you need to use the
+\l {QRemoteObjectNode::acquire} template function to create the Replica
+instance.
 
 A \l {QRemoteObjectDynamicReplica} can be generated at runtime. To do so, you
-call \l {QRemoteObjectNode::acquireDynamic()}, passing in
-the \l {Source} name (a QString) as an argument. Dynamic replicas are a bit
-more verbose to use from C++, but do not require compilation.
-Dynamic replicas do not support initial property values, and do not support
-introspection until they have been initialized.
+call \l {QRemoteObjectNode::acquireDynamic()}, passing in the source name
+(a QString) as an argument. Dynamic replicas are a bit more verbose to use from
+C++, but they do not require compilation. Dynamic replicas do not support
+initial property values, or introspection until they have been initialized.
 
 An important difference between these two ways of creating replicas is the
 behavior before the replica is initialized. Since a dynamic replica only gets
-a metaObject after initialization, it basically has no API before
-initialization. No properties, and no signals to connect slots to.
-Due to the compile-time creation of the metaObject for compiled replicas,
-their API is available when the replica is instantiated. You can even provide
-default values for properties in the template file, which will be used until
-the replica is initialized with current values from the source.
+a metaObject after initialization, it has basically no API before
+initialization -- no properties, and no signals to connect slots to.
 
-See \l {QRemoteObjectReplica} and \l {QRemoteObjectDynamicReplica}
+Because metaObjects for compiled replicas are created at compile-time, their
+API is available when the replica is instantiated. You can even provide default
+values for properties in the template file, which are used until the replica is
+initialized with current values from the source.
 
 \section1 Replica Initialization
 
-A host node will share the list of sources it hosts with every other node that
-connects to it. It will send updates when sources are added or removed from the
-list. In this way, a connected node will always know what sources it can attach
-to. Changes to a specific \l {Source} are only propagated to nodes that have a replica of
-that source. This avoids unnecessary network traffic.
+A host node will share the list of sources that it hosts with every other node
+that connects to it. This host sends updates when sources are added to or
+removed from the list. In this way, a connected node will always know what
+sources it can attach itself to. Changes to a specific source are only
+propagated to nodes that have a replica of that source. Consequently, this
+avoids any unnecessary network traffic.
 
-When a node acquires a replica for a known source, it sends a
-request for that source to the host node. Upon receipt of this request, the
-host will create a reply packet with the current values of all properties of
-the source. If the requested replica is dynamic, it will include the API
-definition for the source. The replica's node will be included in the list of
-connections that receive changes to that source from then on.
+When a node acquires a replica for a known source, it sends a request for that
+source to the host node. Upon receiving this request, the host creates a reply
+packet with the current values for all properties of that source. If the
+requested replica is \l{QRemoteObjectDynamicReplica}{dynamic}, the reply packet
+includes the API definition for the source. From then on, the replica's node
+will be included in the list of connections that receive changes to that
+source.
 
 If a replica is instantiated but its node is not connected to the node that
-hosts the requested source (or that object lives in a host node process, but
-sharing/remoting has not been enabled for the QObject), the Replica will still
-be created, but will remain uninitialized.
+hosts the requested source -- or that object lives in a host node process, but
+sharing/remoting has not been enabled for the QObject -- the Replica will still
+be created, but remain uninitialized.
 
-If, at a later time, the replica's node gets notified that the requested source is
-available from a connected node, it will at that point request the source and
-start the initialization process.
+If, at a later time, the replica's node gets notified that the requested source
+is available from a connected node, at that point it will request the source
+and start the initialization process.
 
 If the connection to a host node is lost, the replica will transition to the
 invalid state. It will attempt to reconnect and will re-initialize if the
-connection is restored (this making sure all properties are current).
-
+connection is restored; this makes sure all properties are current.
 
 \section1 Replica Ownership
 
 The acquire methods return a pointer to the replica QObject instantiated by the
-node. The node has no way of knowing the intended lifetime of the replica, so
-it is the responsibility of the calling program to delete the replica when it
-is no longer needed.
+node. The node has no way of knowing the replica's intended lifetime.
+Consequently, when the replica is not longer needed, it is the calling
+program's responsibility to delete it.
+
+You can instantiate multiple copies of the same replica. All replicas of the
+same source from a single node will share a private data member which handles
+the network communication. This means multiple instances of a replica do not
+introduce additional network traffic, although there will be some additional
+processing overhead. Failing to delete replicas will prevent the reference
+count on this private object from reaching 0, and cause unnecessary network
+communication until the calling process exits. For this reason, it is
+recommended to use \l {QScopedPointer} or \l {QSharedPointer} to help track
+the lifetime of replicas.
 
-You can instantiate multiple copies of the same replica. All replicas of the same
-source from a single node will
-share a private data member which handles the network communication. This means
-multiple instances of a \l {Replica} do not introduce additional network
-traffic, although there will be some additional processing overhead. Failing to
-delete replicas will prevent the reference count on this private object from reaching 0,
-and cause unnecessary network communication until the calling process
-exits. For this reason, it is recommended that \l {QScopedPointer} or \l
-{QSharedPointer} be used to help track replica lifetime.
 */