Document the modelviewclient and server examples

They're simple, which makes them easy to follow.

Adjusted the qtremoteobjects.qdocconf file as it wasn't working with
the examples on my Linux machine at least.

Task-number: QTBUG-90848
Change-Id: Id674585835717be87344f3f694ab77128ecb5344
Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 168 insertions, 18 deletions

diff --git a/examples/remoteobjects/modelviewclient/doc/src/modelviewclient.qdoc b/examples/remoteobjects/modelviewclient/doc/src/modelviewclient.qdoc
new file mode 100644
index 0000000..dc54e2f
--- /dev/null
+++ b/examples/remoteobjects/modelviewclient/doc/src/modelviewclient.qdoc
@@ -0,0 +1,56 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example modelviewclient
+    \title Model-View Client
+
+    This is the client-side application that accompanies the
+    \l {Model-View Server}.
+
+    This example showcases how to make a very simple client program which
+    displays the content and changes made on a server.
+
+    \snippet modelviewclient/main.cpp ObjectNode creation
+
+    We start by creating a QRemoteObjectNode and connecting it to a registry
+    found on the local machine. We also set a
+    \l{QRemoteObjectNode::heartbeatInterval}{heartbeat interval}.
+    The heartbeat is useful to detect if the connection to the \l{Source} has
+    been disrupted. In this case, since all the traffic is local, it would
+    detect when the server has been closed.
+
+    \snippet modelviewclient/main.cpp Model acquisition
+
+    We then \l {QRemoteObjectNode::acquireModel}{acquire} the model which
+    contains all of our data. In this case, we're looking to acquire a model
+    named \c{RemoteModel} from the remote object network we are connected to.
+
+    \snippet modelviewclient/main.cpp QTreeView-creation
+
+    And finally, we display the model in a very basic application.
+*/
diff --git a/examples/remoteobjects/modelviewclient/main.cpp b/examples/remoteobjects/modelviewclient/main.cpp
index 7848198..a3361df 100644
--- a/examples/remoteobjects/modelviewclient/main.cpp
+++ b/examples/remoteobjects/modelviewclient/main.cpp
@@ -63,16 +63,21 @@ int main(int argc, char **argv)
 
     QApplication app(argc, argv);
 
-
-
+//! [ObjectNode creation]
     QRemoteObjectNode node(QUrl(QStringLiteral("local:registry")));
     node.setHeartbeatInterval(1000);
+//! [ObjectNode creation]
+//! [Model acquisition]
+    QScopedPointer<QAbstractItemModelReplica> model(node.acquireModel(QStringLiteral("RemoteModel")));
+//! [Model acquisition]
+
+//! [QTreeView-creation]
     QTreeView view;
     view.setWindowTitle(QStringLiteral("RemoteView"));
     view.resize(640,480);
-    QScopedPointer<QAbstractItemModelReplica> model(node.acquireModel(QStringLiteral("RemoteModel")));
     view.setModel(model.data());
     view.show();
+//! [QTreeView-creation]
 
     return app.exec();
 }
diff --git a/examples/remoteobjects/modelviewserver/doc/src/modelviewserver.qdoc b/examples/remoteobjects/modelviewserver/doc/src/modelviewserver.qdoc
new file mode 100644
index 0000000..789af82
--- /dev/null
+++ b/examples/remoteobjects/modelviewserver/doc/src/modelviewserver.qdoc
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example modelviewserver
+    \title Model-View Server
+
+    This is the server-side application that accompanies the
+    \l {Model-View Client}.
+
+    This example showcases how to make a simple server program that displays
+    and makes changes to a QTreeView which is made available on a Remote
+    Objects network.
+
+    \snippet modelviewserver/main.cpp RegistryHost setup
+
+    We start by creating a QRemoteObjectRegistryHost with which other
+    Remote Objects will connect, be registered and then be advertised by.
+    The model we create can then be easily acquired from the client side by just
+    connecting to the registry.
+
+    \snippet modelviewserver/main.cpp Model-creation and role-selection
+
+    Now we have to create the model we need. The exact implementation is
+    available in the source code, to which you can navigate by pressing the
+    link further down on this page. We also define which \e roles we want to
+    expose to the \l{Replica} on the client side.
+
+    \snippet modelviewserver/main.cpp Model-remoting
+
+    Here, we create the QRemoteObjectHost that connects to, and shares all its
+    Remote Objects with, the Registry we created earlier. We then start remoting
+    the model we just created with the name \c{RemoteModel}. We also pass the
+    \e roles argument here.
+
+    \snippet modelviewserver/main.cpp TreeView-creation
+
+    We then display the model with a QTreeView widget.
+
+    \snippet modelviewserver/main.cpp Automated actions
+
+    For the sake of keeping the example light-weight it performs some
+    automated actions to affect the model shortly after the server application
+    launches. These changes can then be seen on both the server and client side.
+    You can also change the text in the fields on the server side and see it
+    update on the client side.
+*/
diff --git a/examples/remoteobjects/modelviewserver/main.cpp b/examples/remoteobjects/modelviewserver/main.cpp
index 53627f4..d86c688 100644
--- a/examples/remoteobjects/modelviewserver/main.cpp
+++ b/examples/remoteobjects/modelviewserver/main.cpp
@@ -54,6 +54,7 @@
 #include <QStandardItemModel>
 #include <QStandardItem>
 
+#include <memory>
 
 struct TimerHandler : public QObject
 {
@@ -108,18 +109,14 @@ QList<QStandardItem*> addChild(int numChildren, int nestingLevel)
     return result;
 }
 
-int main(int argc, char *argv[])
+std::unique_ptr<QStandardItemModel> createModel()
 {
-    QLoggingCategory::setFilterRules("qt.remoteobjects.debug=false\n"
-                                     "qt.remoteobjects.warning=false");
-    QApplication app(argc, argv);
-
+    std::unique_ptr<QStandardItemModel> sourceModel = std::make_unique<QStandardItemModel>();
     const int modelSize = 100000;
     QStringList list;
-    QStandardItemModel sourceModel;
     QStringList hHeaderList;
     hHeaderList << QStringLiteral("First Column with spacing") << QStringLiteral("Second Column with spacing");
-    sourceModel.setHorizontalHeaderLabels(hHeaderList);
+    sourceModel->setHorizontalHeaderLabels(hHeaderList);
     list.reserve(modelSize);
     for (int i = 0; i < modelSize; ++i) {
         QStandardItem *firstItem = new QStandardItem(QStringLiteral("FancyTextNumber %1").arg(i));
@@ -130,8 +127,7 @@ int main(int argc, char *argv[])
             firstItem->setBackground(Qt::red);
         QList<QStandardItem*> row;
         row << firstItem << secondItem;
-        sourceModel.invisibleRootItem()->appendRow(row);
-        //sourceModel.appendRow(row);
+        sourceModel->invisibleRootItem()->appendRow(row);
         list << QStringLiteral("FancyTextNumber %1").arg(i);
     }
 
@@ -140,28 +136,50 @@ int main(int argc, char *argv[])
         {Qt::DisplayRole, "_text"},
         {Qt::BackgroundRole, "_color"}
     };
-    sourceModel.setItemRoleNames(roleNames);
+    sourceModel->setItemRoleNames(roleNames);
+    return sourceModel;
+}
 
-    QList<int> roles;
-    roles << Qt::DisplayRole << Qt::BackgroundRole;
+int main(int argc, char *argv[])
+{
+    QLoggingCategory::setFilterRules("qt.remoteobjects.debug=false\n"
+                                     "qt.remoteobjects.warning=false");
+    QApplication app(argc, argv);
 
     qDebug() << "Creating registry host";
+//! [RegistryHost setup]
     QRemoteObjectRegistryHost node(QUrl(QStringLiteral("local:registry")));
+//! [RegistryHost setup]
 
+//! [Model-creation and role-selection]
+    std::unique_ptr<QStandardItemModel> sourceModel = createModel();
+
+    QList<int> roles;
+    roles << Qt::DisplayRole << Qt::BackgroundRole;
+//! [Model-creation and role-selection]
+
+//! [Model-remoting]
     QRemoteObjectHost node2(QUrl(QStringLiteral("local:replica")), QUrl(QStringLiteral("local:registry")));
-    node2.enableRemoting(&sourceModel, QStringLiteral("RemoteModel"), roles);
+    node2.enableRemoting(sourceModel.get(), QStringLiteral("RemoteModel"), roles);
+//! [Model-remoting]
 
+//! [TreeView-creation]
     QTreeView view;
     view.setWindowTitle(QStringLiteral("SourceView"));
-    view.setModel(&sourceModel);
+    view.setModel(sourceModel.get());
     view.show();
+//! [TreeView-creation]
+
+//! [Automated actions]
     TimerHandler handler;
-    handler.model = &sourceModel;
+    handler.model = sourceModel.get();
     QTimer::singleShot(5000, &handler, &TimerHandler::changeData);
     QTimer::singleShot(10000, &handler, &TimerHandler::insertData);
     QTimer::singleShot(11000, &handler, &TimerHandler::changeFlags);
     QTimer::singleShot(12000, &handler, &TimerHandler::removeData);
     QTimer::singleShot(13000, &handler, &TimerHandler::moveData);
+//! [Automated actions]
+
 
     return app.exec();
 }