From 23c061970fdf9a826d277c05addf3d448ac2b930 Mon Sep 17 00:00:00 2001 From: Frederik Gladhorn Date: Mon, 30 Dec 2013 13:37:59 +0100 Subject: Improve and share model documentation Expand the docs and make them shared. Change-Id: I00a629ea00006a9f3652d3d54f51f4811d15a6cc Reviewed-by: Mitch Curtis --- doc/shared/model-append.qdocinc | 13 +++++++++++++ doc/shared/model-query.qdocinc | 19 +++++++++++++++++++ doc/shared/model-remove.qdocinc | 8 ++++++++ 3 files changed, 40 insertions(+) create mode 100644 doc/shared/model-append.qdocinc create mode 100644 doc/shared/model-query.qdocinc create mode 100644 doc/shared/model-remove.qdocinc (limited to 'doc') 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 -- cgit v1.2.1