Improve and share client docs

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

8 files changed, 108 insertions, 1 deletions

diff --git a/doc/shared/client-create.qdocinc b/doc/shared/client-create.qdocinc
new file mode 100644
index 0000000..abf060d
--- /dev/null
+++ b/doc/shared/client-create.qdocinc
@@ -0,0 +1,26 @@
+\brief Insert a new \a object into the database.
+
+The returned \l EnginioReply indicates the success of the object creation.
+The object becomes available from the backend if it finishes without errors.
+
+\a operation determines the kind of object created. For example a regular object
+or a user or usergroup.
+By default, \l Enginio::ObjectOperation is used and regular objects created.
+\note that the \tt objectType is required for regular objects and has to begin with
+\tt {"objects."}.
+
+The JSON for the object that will be created must follow this structure:
+\code
+{
+    "objectType": "object.myType",
+    "name" : "A thing",
+    "price" : "5",
+}
+\endcode
+Where only the \tt objectType property is required and \tt name and \tt price
+are examples of custom properties.
+
+Users and all kinds of other objects are created the same way but do not require any
+\tt objectType.
+
+\sa EnginioReply, query(), update(), remove(), Enginio::Operation
diff --git a/doc/shared/client-downloadUrl.qdocinc b/doc/shared/client-downloadUrl.qdocinc
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/shared/client-downloadUrl.qdocinc
diff --git a/doc/shared/client-fullTextSearch.qdocinc b/doc/shared/client-fullTextSearch.qdocinc
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/shared/client-fullTextSearch.qdocinc
diff --git a/doc/shared/client-query.qdocinc b/doc/shared/client-query.qdocinc
new file mode 100644
index 0000000..1c4499a
--- /dev/null
+++ b/doc/shared/client-query.qdocinc
@@ -0,0 +1,37 @@
+\brief Query the database
+
+The \a query is an object containing the actual query to the backend.
+The query will be run on the \a operation part of the backend.
+
+The \a query has to contain an "objectType" which has to point to a type defined
+in the backend. Optionally, it can also contain:
+\list
+\li query - describes how objects are queried, allows filtering of results. See {https://engin.io/documentation/rest/parameters/queries}
+{JSON query structure}
+\li limit - limits how many objects the server should return (default value is \c 100).
+\li offset - how many objects the server should skip from the beginning of the returned results. Note that the server keeps the data
+in random order so that usage of offset implies using \c sort as well.
+\li sort - describes how results are sorted. See \l{https://engin.io/documentation/rest/parameters/sort}{JSON sort request structure}
+\li count - if the \c count is set, the server will return only count of matching objects
+\li include - describes which other objects are included in the response. See \l{https://engin.io/documentation/rest/parameters/include}
+{JSON include structure}
+\endlist
+
+The JSON to list all objects of type "objects.image":
+\code
+{
+    "objectType": "objects.image"
+}
+\endcode
+
+An example using \tt include to get \tt file references and with a query parameter that
+limits the results to only those objects where the reference is valid:
+\code
+{
+    "objectType": "objects.image",
+    "include": {"file": {}},
+    "query" : { "file": { "$ne": null } }
+}
+\endcode
+
+\sa EnginioReply, create(), update(), remove()
diff --git a/doc/shared/client-remove.qdocinc b/doc/shared/client-remove.qdocinc
new file mode 100644
index 0000000..995554c
--- /dev/null
+++ b/doc/shared/client-remove.qdocinc
@@ -0,0 +1,16 @@
+\brief Remove an object from the database.
+
+The \a object that is to be removed is identified by its object ID and if it is a regular object also \tt objectType.
+
+The JSON that identfies an object looks like this:
+\code
+{
+    "objectType": "objects.images",
+    "id": "52b1a94b5a3d8b15b1037ff5"
+}
+\endcode
+
+The \a operation is the area from which the object gets removed.
+It defaults to \l Enginio::ObjectOperation to remove regular objects by default.
+
+\sa EnginioReply, create(), query(), update()
diff --git a/doc/shared/client-update.qdocinc b/doc/shared/client-update.qdocinc
new file mode 100644
index 0000000..f1d0874
--- /dev/null
+++ b/doc/shared/client-update.qdocinc
@@ -0,0 +1,28 @@
+\brief Update an object in the database.
+
+The \a operation is the area in which the \a object gets updated. It defaults to \l Enginio::ObjectOperation
+to update regular objects by default.
+
+To change the name property of an object to "New Name", use the following JSON:
+\code
+{
+    "id": "objectId",
+    "objectType": "objects.objectType",
+    "name": "New Name"
+}
+\endcode
+
+All other existing properties of the object are not affected by the update.
+
+To update the access control list of an object, use the following JSON:
+\code
+{
+    "id": "objectId",
+    "objectType": "objects.objectType",
+    "access": { "read": ["id": "userId", "objectTypes": "users"],
+                "update": ["id": "userId", "objectTypes": "users"],
+                "admin": ["id": "userId", "objectTypes": "users"] }
+}
+\endcode
+
+\sa EnginioReply, create(), query(), remove()
diff --git a/doc/shared/client-uploadFile.qdocinc b/doc/shared/client-uploadFile.qdocinc
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/shared/client-uploadFile.qdocinc
diff --git a/doc/shared/model-append.qdocinc b/doc/shared/model-append.qdocinc
index 65f8314..cf1bb5d 100644
--- a/doc/shared/model-append.qdocinc
+++ b/doc/shared/model-append.qdocinc
@@ -1,4 +1,4 @@
-\brief Add a new object to the model and database.
+\brief Add a new \a 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.