Improve and share model documentation

Expand the docs and make them shared.

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

3 files changed, 40 insertions, 0 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