Doc: Improve conceptual content for Node and Source

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

2 files changed, 125 insertions, 105 deletions

diff --git a/src/remoteobjects/doc/src/remoteobjects-nodes.qdoc b/src/remoteobjects/doc/src/remoteobjects-nodes.qdoc
index 65778a9..7811cbf 100644
--- a/src/remoteobjects/doc/src/remoteobjects-nodes.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-nodes.qdoc
@@ -27,63 +27,78 @@
 /*!
 \page qtremoteobjects-node.html
 \title Qt Remote Objects Nodes
-\brief Describes how Qt Remote Objects Nodes pass data between nodes.
-\section1 Nodes
+\brief Describes how Qt Remote Objects pass data between nodes.
 
-QRemoteObjectNodes (Nodes) are what enable
-the passing of information between processes. All QtRO functionality is
-enabled by a small number of distinct packets passing the necessary data
-between nodes.
+In a QtRO network, information is passed between processes via
+QRemoteObjectNodes ("nodes"). This peer-to-peer functionality uses a small
+number of distinct packets passing the necessary data between nodes.
 
-Each process that participates in QtRO's IPC will instantiate a Node-based type
-(QRemoteObjectNode, QRemoteObjectHost, or QRemoteObjectRegistryHost). The
-host types of Nodes provide additional functionality. Both QRemoteObjectHost
-and QRemoteObjectRegistryHost support the \l {QRemoteObjectHostBase::}{enableRemoting()}
-(and the corresponding \l {QRemoteObjectHostBase::}{disableRemoting()}) methods,
-which are the key methods to expose \l Source objects to the network. In order
-to use the \l Registry functionality, there should be a QRemoteObjectRegistryHost
-on the network.
-All other nodes can then pass the RegistryHost's URL to the Node's \e registryAddress
-constructor parameter, or pass the URL to the \l {QRemoteObjectNode::}{setRegistryUrl()}
-method.
+Each process that participates in the network instantiates a Node-based type,
+such as QRemoteObjectNode, QRemoteObjectHost, or QRemoteObjectRegistryHost.
+The host types of Nodes provide additional functionality. Both
+QRemoteObjectHost and QRemoteObjectRegistryHost support the
+\l{QRemoteObjectHostBase::}{enableRemoting()} and the corresponding
+\l{QRemoteObjectHostBase::}{disableRemoting()}) methods, which are the key
+methods to expose source objects to the network. To use the \l Registry
+functionality, you need to have a QRemoteObjectRegistryHost on the network.
+Then, all other nodes can pass the RegistryHost's URL to the Node's
+\c registryAddress constructor parameter, or pass the URL to the
+\l {QRemoteObjectNode::}{setRegistryUrl()} method.
 
-QtRO works as a peer-to-peer network. That is, in order to \l
-{QRemoteObjectNode::acquire()}{acquire()} a valid \l {Replica}, the \l
-{Replica}'s node needs a connection to the node that hosts its \l {Source}. A
-host node is a node that allows other nodes to connect to it, which is
-accomplished by giving hosts unique addresses (the address is provided to the
-QRemoteObjectHost constructor or set by the setHostUrl method). The node that a
-\l {Replica} is requested from must establish the connection to the host node
-in order to initialize the \l {Replica} and keep it up to date.
+Since QtRO is a peer-to-peer network, to
+\l{QRemoteObjectNode::acquire()}{acquire()} a valid \l{Replica}, the replica's
+node needs to be connected to the node that hosts its \l{Source}. A host node is a
+node that allows other nodes to connect to it, which is accomplished by giving
+hosts unique addresses. This address is provided to the QRemoteObjectHost
+constructor or set by the setHostUrl method. The node from which a replica is
+requested must establish the connection to the host node, to initialize the
+replica and keep it up to date.
 
 \section1 Connecting Nodes using QtRO URLs
 
-Host Nodes use custom URLs to simplify connections. While the list will likely
-be extended, QtRO currently supports two types of connections. A "tcp"
-connection (using the standard tcp/ip protocol) supports connections between
-devices as well as between processes on the same device. A "local" connection
-(which can have less overhead, depending on the underlying OS features) only supports
-connections between processes on the same device.
+Host Nodes use custom URLs to simplify connections. Currently, QtRO supports
+two types of connections:
 
-When using a local connection, a unique name must be used. For tcp connections,
-a unique address and port number combination much be used.
+\list 1
+    \li A TCP connection using the standard TCP/IP protocol - supports
+        connections between devices as well as between processes on the same
+        device.
+    \li A local connection - supports connections between processes on the same
+        device. This type of connection can have less overhead, depending on
+        the underlying Operating System features.
+\endlist
 
-There is currently no \l {http://www.zeroconf.org/} {zeroconf} facility
-included in QtRO. All processes or devices must therefore know beforehand how to
-connect to each other. A \l {QRemoteObjectRegistry} (see below) can be used to
-simplify the connection process for a network with multiple Host Nodes.
+For local connections, you must use a unique name. For TCP connections, you
+must provide a unique address and port number combination.
+
+Currently, QtRO does not include a \l {http://www.zeroconf.org/} {zeroconf}
+facility. Therefore, all processes or devices must know beforehand, how to
+connect to each other. A \l {QRemoteObjectRegistry} can be used to simplify
+the connection process for a network with multiple Host Nodes.
+
+The table below summarizes the connection types available:
 
-Connection types are summarized in the following table.
     \table 90%
-    \header \li URL  \li Host Node           \li Connecting Node
-    \row    \li \l {QUrl}("local:service")   \li \l {QLocalServer}("service") \li \l {QLocalSocket}("service")
-    \row    \li \l {QUrl}("tcp://192.168.1.1:9999")   \li \l {QTcpServer}("192.168.1.1",9999) \li \l {QTcpSocket}("192.168.1.1",9999)
+    \header
+        \li URL
+        \li Host Node
+        \li Connecting Node
+    \row
+        \li \l {QUrl}("local:service")
+        \li \l {QLocalServer}("service")
+        \li \l {QLocalSocket}("service")
+    \row
+        \li \l {QUrl}("tcp://192.168.1.1:9999")
+        \li \l {QTcpServer}("192.168.1.1",9999)
+        \li \l {QTcpSocket}("192.168.1.1",9999)
     \endtable
 
-Nodes have a couple of \l {QRemoteObjectHostBase::enableRemoting()}
-{enableRemoting()} methods that are used to share objects on the network (this
-will produce an error if the Node is not a Host Node however). Other
-processes/devices that want to interact with a shared object use one of the \l
-{QRemoteObjectNode::acquire()} {node's acquire()} methods to instantiate a
-replica.
+Nodes have a few \l{QRemoteObjectHostBase::enableRemoting()}
+{enableRemoting()} methods that are used to share objects on the network.
+However, if the node is not a host node, an error is returned.
+
+Other processes or  devices that want to interact with a shared object can
+use one of the \l{QRemoteObjectNode::acquire()} {node's acquire()} methods,
+to instantiate a replica.
+
 */
diff --git a/src/remoteobjects/doc/src/remoteobjects-source.qdoc b/src/remoteobjects/doc/src/remoteobjects-source.qdoc
index fd97027..d18c1be 100644
--- a/src/remoteobjects/doc/src/remoteobjects-source.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-source.qdoc
@@ -27,86 +27,91 @@
 /*!
 \page qtremoteobjects-source.html
 \title Qt Remote Objects Source
-\brief Introduction to using Source
+\brief Describes the concept of a source and how to use the source header that the repc generates.
 \target Source
-\section1 Source Objects
 
-A Remote Object Source is the QObject that is responsible for the
-implementation of the exposed API.
+A QRemoteObjectSource ("source") is the QObject that is responsible for
+implementing the exposed API.
 
-At a high level, you have a choice of using a QObject type directly as a source
-or defining the desired API in a .rep template for use with the \l {repc}
-compiler.
+At a high level, you can choose to use a QObject type directly as a source; or
+you can define the desired API in a \c{.rep} template for use with the
+\l {repc} compiler.
 
-If you already have a fully defined QObject, it can become a Source simply by
-passing it to \l {QRemoteObjectHostBase::enableRemoting()}. This lets other
-processes/devices create a \l {Replica} of the object to interact with (see \l
-{Remote Object Interaction}). You can then instantiate \l {QRemoteObjectDynamicReplica}s
-of your object.
+If you already have a fully defined QObject, you can use it as a source by
+passing it to \l {QRemoteObjectHostBase::enableRemoting()}. This way, other
+processes or devices can then create
+\l{QRemoteObjectDynamicReplica}{dynamics replicas} of the object to interact
+with.
 
-Letting \l {repc} generate a \l {Source} header file for your project (using
-the \l {REPC_SOURCE} variable) provides three options for implementing the desired
-API. If your class name was Foo, the options would be the following (see \l
-{The rep file format} for help in creating a rep file)
+For more information, see \l{Remote Object Interaction}).
+
+Letting repc generate a source header file for your project, using the
+\l {REPC_SOURCE} variable, provides three different options to implement the
+required API.
+
+Suppose your class name is Foo, you then have the following options:
 
 \list
-\li \l {TypeSimpleSource} {FooSimpleSource} inheritance
-\li \l {TypeSource} {FooSource} inheritance
-\li \l {TypeAPI} {FooSourceAPI} usage with your own QObject
+    \li \l {TypeSimpleSource} {FooSimpleSource} inheritance
+    \li \l {TypeSource} {FooSource} inheritance
+    \li \l {TypeAPI} {FooSourceAPI} usage with your own QObject
 \endlist
 
+For more details on how to create a \c{.rep} file, see \l{The rep file format}.
+
 \target TypeSimpleSource
-There is a <Type>SimpleSource class defined in the header, which provides
+There is a <Type>SimpleSource class defined in the header, which provides the
 basic getter/setter methods for each property and implements data members of
-the correct property type in the header. Here "<Type>" represents the class
-name from the .rep file, so if your class is of type "MyType" in the .rep file,
-there will be a MyTypeSimpleSource class declared in the generated header file.
-This is a fast way to get started using the API. To use this class, you need to
-inherit from this class and implement any defined slots (which are pure virtual
-in the generated header file). Whatever logic is needed to manage the
-exposed properties and emit signals would be added to
-the inheriting class as well.
+the correct property type in the header. "<Type>" here represents the class
+name from the \c{.rep} file, so if your class is of type "MyType" in the
+\c{.rep} file, then the generated header file will have a MyTypeSimpleSource
+class declared. This is a quick way to get started using the API. To use this
+class, you need to write a class that inherits from it and implement any slots
+defined, which are marked as pure virtual in the generated header file.
+You need to add the necessary logic to manage the exposed properties and emit
+signals, to your class as well.
 
 \target TypeSource
-If you need to hide the implementation details, you can use the <Type>Source
-class instead, which is the 2nd class declared in the header
-file. This class definition does not provide data members, and makes the
-getter/setter functions pure virtual as well. You have more flexibility in how
-you implement the class, although you need to write more code.
+If you need to hide your implementation details, use the second class declared
+in the header file, the <Type>Source class. This class' definition does not
+provide data members, and also makes the getter/setter functions pure virtual.
+While you may need to write more code, using this class gives you more
+flexibility in your implementation.
 
 \target TypeAPI
-Finally, there is the <Type>SourceAPI class generated in the header. This is a
-templated class, for use specifically by the templated version of \l
-{QRemoteObjectHostBase::enableRemoting()}, which allows you to
-use any QObject that supports the desired API as the source. You will get
-compile-time warnings if the class does not provide the correct API, and using
-this class allows you to hide or convert properties or signal/slot parameters.
+The third class generated in the header is <Type>SourceAPI. This is a templated
+class, for use specifically by the templated version of
+\l {QRemoteObjectHostBase::enableRemoting()}, which allows you to use any
+QObject that supports the required API as the source. Use this class to hide or
+convert properties or signal/slot parameters. If your implementation
+does not provide the correct API, there will be compile-time warnings.
 
-\note The QObject API is \b never exposed. For instance, while a \l
-{Replica} will have a destroyed signal, the destroyed signal of the source is
-not propagated. The \l {Source} and each \l {Replica} are unique QObjects with
-their own connections. The API that is exposed is defined by the .rep template
-used by \l {repc}, or in the case of raw QObjects, all API elements defined in
-the inheritance chain from a specific ancestor. Unless you define
-Q_CLASSINFO("RemoteObject Type") in an ancestor, the QObject's parent is used.
-If Q_CLASSINFO("RemoteObject Type") is used, that class's API is the lowest
+\note Replicas and sources both derive from QObject; but their QObject API is
+\b never exposed. For instance, while a replica has a \l{QObject::}{destroyed}
+signal, the source's \l{QObject::}{destroyed} signal is not propagated. The
+source and each of its replica are unique QObjects with their own connections
+and lifetimes. Instead, the API that is exposed is defined by the \c{.rep}
+template used by repc. In the case of raw QObjects, all API elements are defined
+in the inheritance chain from a specific ancestor. The QObject's parent is always
+used, unless you define \c{Q_CLASSINFO("RemoteObject Type")} in an ancestor. If
+you use \c{Q_CLASSINFO("RemoteObject Type")}, that class's API is the lowest
 level of API used.
 
 \section1 Identifying Sources
 
-Since more than one \l {Source} can be shared by a host node, each \l
-{Source} requires a name. All \l {repc} generated headers include a way for the
-node to determine the class name (Q_CLASSINFO for replica/simplesource/source
-types, or a static name() function for the SourceAPI type). If you pass your
-own QObject type to \l {QRemoteObjectHostBase::enableRemoting()}, the name will
-be determined using the following logic:
+Because a host node can share more than one source, each source requires a name.
+All repc-generated headers include a way for the node to determine the class name:
+Q_CLASSINFO for replica, simplesource, or source types; or a static \c name()
+function for the SourceAPI type. If you pass your own QObject type to
+\l {QRemoteObjectHostBase::enableRemoting()}, the name is determined using the
+following logic:
 \list
     \li A name can optionally be passed to \l {QRemoteObjectHostBase::enableRemoting()}.
-        If provided, that name will be used.
+        If provided, that name is used.
     \li If the object or any of its ancestors has Q_CLASSINFO of type
-        "RemoteObject Type" defined, the defined type name will be used.
-    \li Otherwise, the QObject's objectName (if set) will be
-        used. \li If none of the above are available, the call to
-        \l {QRemoteObjectHostBase::enableRemoting()} will fail, returning false.
+        "RemoteObject Type" defined, that type name is used.
+    \li If the QObject's objectName is set, then it is used.
+    \li If none of the above are available, the call to
+        \l {QRemoteObjectHostBase::enableRemoting()} fails, returning false.
 \endlist
 */