Improve and share model documentation

Expand the docs and make them shared.

Change-Id: I00a629ea00006a9f3652d3d54f51f4811d15a6cc
Reviewed-by: Mitch Curtis <mitch.curtis@digia.com>

7 files changed, 56 insertions, 27 deletions

diff --git a/doc/shared/model-append.qdocinc b/doc/shared/model-append.qdocinc
new file mode 100644
index 0000000..65f8314
--- /dev/null
+++ b/doc/shared/model-append.qdocinc
@@ -0,0 +1,13 @@
+\brief Add a new object to the model and database.
+
+This function appends the new object to the local model cache
+and makes an asynchronous request to the backend.
+
+Since adding an object to the database may fail for various reasons,
+the returned reply must be kept and used for error handling (see \l EnginioReply).
+If the operation fails, the object that was supposed to be appended will be removed
+from the local model again. If the model is used in a view and the backend does
+not accept the object because it violates a validator, it will be visible to the
+user that a new row in the view appears and disappears again.
+
+\return the EnginioReply from the backend
diff --git a/doc/shared/model-query.qdocinc b/doc/shared/model-query.qdocinc
new file mode 100644
index 0000000..bdba13a
--- /dev/null
+++ b/doc/shared/model-query.qdocinc
@@ -0,0 +1,19 @@
+\brief The query used to populate the model with data from the backend.
+
+It takes the same argument as \l EnginioClient::query(), so that the documentation
+for \l EnginioClient::query() can be consulted regarding how to construct the query.
+
+While \l EnginioClient::query() returns the data of a query as a JSON
+object, for the model the query will be interpreted as the model data.
+
+Usually the query is for one object type and will return all objects
+in the database of that type. The model will then represent each returned object
+as one row. It can be limited and sorted just like its counterpart
+in EnginioClient.
+
+One important thing to note is that the model cannot keep the same sorting as
+the backend and thus sorting and limits are only preserved until
+an insertion or deletion happens.
+
+\return the EnginioReply from the backend
+\sa EnginioClient::query()
diff --git a/doc/shared/model-remove.qdocinc b/doc/shared/model-remove.qdocinc
new file mode 100644
index 0000000..94de12d
--- /dev/null
+++ b/doc/shared/model-remove.qdocinc
@@ -0,0 +1,8 @@
+
+\brief Removes the \a row from the model and database.
+
+This function immediately removes the \a row from the local cache
+and sends a remove request to the Enginio backend.
+
+\return the EnginioReply from the backend
+\sa EnginioClient::remove()
\ No newline at end of file
diff --git a/src/enginio_client/doc/qtenginio.qdocconf b/src/enginio_client/doc/qtenginio.qdocconf
index 402da1b..50bc32b 100644
--- a/src/enginio_client/doc/qtenginio.qdocconf
+++ b/src/enginio_client/doc/qtenginio.qdocconf
@@ -7,7 +7,9 @@ description = Client library for Enginio
 url = http://engin.io
 version = $QT_VERSION
 
-sourcedirs += ..
+sourcedirs += ..  \
+    ../../../doc/shared
+
 headerdirs += ..
 
 imagedirs += images
diff --git a/src/enginio_client/enginiomodel.cpp b/src/enginio_client/enginiomodel.cpp
index d9063a5..427d3ef 100644
--- a/src/enginio_client/enginiomodel.cpp
+++ b/src/enginio_client/enginiomodel.cpp
@@ -427,11 +427,8 @@ void EnginioModel::setClient(const EnginioClient *client)
 
 /*!
   \property EnginioModel::query
-  \brief The query which returns the data for the model.
 
-  Sorting preserved until insertion/deletion
-
-  \sa EnginioClient::query()
+  \include model-query.qdocinc
 */
 QJsonObject EnginioModel::query()
 {
@@ -469,12 +466,10 @@ void EnginioModel::setOperation(Enginio::Operation operation)
 }
 
 /*!
-  Append \a value to this model local cache and send a create request
-  to enginio backend.
-  \return reply from backend
+  \include model-append.qdocinc
   \sa EnginioClient::create()
 */
-EnginioReply *EnginioModel::append(const QJsonObject &value)
+EnginioReply *EnginioModel::append(const QJsonObject &object)
 {
     Q_D(EnginioModel);
     if (Q_UNLIKELY(!d->enginio())) {
@@ -482,14 +477,11 @@ EnginioReply *EnginioModel::append(const QJsonObject &value)
         return 0;
     }
 
-    return d->append(value);
+    return d->append(object);
 }
 
 /*!
-  Remove a value from \a row in this model local cache and send
-  a remove request to enginio backend.
-  \return reply from backend
-  \sa EnginioClient::remove()
+  \include model-remove.qdocinc
 */
 EnginioReply *EnginioModel::remove(int row)
 {
@@ -536,10 +528,7 @@ EnginioReply *EnginioModel::setData(int row, const QVariant &value, const QStrin
     return d->setValue(row, role, value);
 }
 
-/*!
-    \overload
-    \internal
-*/
+
 Qt::ItemFlags EnginioBaseModel::flags(const QModelIndex &index) const
 {
     return QAbstractListModel::flags(index) | Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable;
diff --git a/src/enginio_plugin/doc/qtenginioqml.qdocconf b/src/enginio_plugin/doc/qtenginioqml.qdocconf
index 4b56046..5d3b091 100644
--- a/src/enginio_plugin/doc/qtenginioqml.qdocconf
+++ b/src/enginio_plugin/doc/qtenginioqml.qdocconf
@@ -7,7 +7,9 @@ description = Client library for Enginio from QML
 url = http://engin.io
 version = $QT_VERSION
 
-sourcedirs += ..
+sourcedirs += .. \
+    ../../../doc/shared
+
 headerdirs += ..
 
 imagedirs += images
diff --git a/src/enginio_plugin/enginioqmlmodel.cpp b/src/enginio_plugin/enginioqmlmodel.cpp
index fbb405e..8e60252 100644
--- a/src/enginio_plugin/enginioqmlmodel.cpp
+++ b/src/enginio_plugin/enginioqmlmodel.cpp
@@ -79,7 +79,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
   \qmlproperty QJSValue EnginioModel::query
-  The query used to populate the model with data.
+  \include model-query.qdocinc
 */
 
 /*!
@@ -93,15 +93,11 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-  \qmlmethod EnginioReply EnginioModel::append(QJSValue value)
-  \brief Add a new object to the model and database.
+  \qmlmethod EnginioReply EnginioModel::append(QJSValue object)
+  \include model-append.qdocinc
 
   To add a "city" object to the model by appending it:
   \snippet models.qml append
-  The append will be reflected by the model immediately and will be propagated
-  to the server asynchronously.
-
-  The returned \l EnginioReply can be used to react to a finished object creation.
 */
 
 /*!
@@ -115,7 +111,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
   \qmlmethod EnginioReply EnginioModel::remove(int row)
-  \brief removes the object at \a row
+  \include model-remove.qdocinc
 */
 
 namespace  {