Add docs

8 files changed, 268 insertions, 37 deletions

diff --git a/doc/snippets/files.qml b/doc/snippets/files.qml
new file mode 100644
index 0000000..04643d7
--- /dev/null
+++ b/doc/snippets/files.qml
@@ -0,0 +1,80 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Enginio Qt Client Library.
+**
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+****************************************************************************/
+
+import QtQuick 2.0
+import Enginio 1.0
+import "../../examples/qml/config.js" as Config
+
+Rectangle {
+    width: 400
+    height: 400
+
+    Enginio {
+        id: client
+        backendId: Config.backendData.id
+        backendSecret: Config.backendData.secret
+        onFinished: console.log("Engino request finished." + reply.data)
+        onError: console.log("Enginio error " + reply.errorCode + ": " + reply.errorString)
+    }
+
+    //! [upload]
+    function upload() {
+        var fileObject = {
+            objectType: "objects.example",
+            name: "Example object with file attachment",
+        }
+        var reply = client.create(fileObject);
+        reply.finished.connect(function() {
+            console.log("Upload finished: " + reply.data().id)
+            var objectId = reply.data().id
+            var fileName = "files.qml"
+            var uploadData = {
+                file: { "fileName": fileName },
+                "targetFileProperty": {
+                    "objectType": "objects.example",
+                    "id": objectId,
+                    "propertyName": "qml_attachment"
+                },
+            };
+            var uploadReply = client.uploadFile(uploadData, fileName)
+            uploadReply.finished.connect(function() { console.log("File uploaded.") })
+        })
+    }
+    //! [upload]
+
+    Component.onCompleted: upload()
+}
diff --git a/doc/snippets/models.qml b/doc/snippets/models.qml
new file mode 100644
index 0000000..ae6e046
--- /dev/null
+++ b/doc/snippets/models.qml
@@ -0,0 +1,98 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Enginio Qt Client Library.
+**
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+****************************************************************************/
+
+import QtQuick 2.0
+import Enginio 1.0
+import "../../examples/qml/config.js" as Config
+
+Rectangle {
+    width: 400
+    height: 400
+
+    Enginio {
+        id: client
+        backendId: Config.id
+        backendSecret: Config.secret
+        onFinished: console.log("Engino request finished." + reply.data)
+        onError: console.log("Enginio error " + reply.errorCode + ": " + reply.errorString)
+    }
+
+    //! [model]
+    EnginioModel {
+        id: enginioModel
+        enginio: client
+        query: { "objectType": "objects.city" }
+    }
+    //! [model]
+
+    //! [view]
+    ListView {
+        anchors.fill: parent
+        model: enginioModel
+        delegate: Text {
+            text: model.name + ": " + model.population
+        }
+    }
+    //! [view]
+
+    Rectangle {
+        color: "lightsteelblue"
+        width: parent.width
+        height: 30
+        anchors.bottom: parent.bottom
+        Text {
+            anchors.centerIn: parent
+            text: "Add Berlin"
+        }
+        MouseArea {
+            anchors.fill: parent
+            onClicked: addCity()
+        }
+    }
+
+    //! [append]
+    function addCity() {
+        var berlin = {
+            "objectType": "objects.city",
+            "name": "Berlin",
+            "population": 3300000
+        }
+        enginioModel.append(berlin)
+    }
+    //! [append]
+
+}
diff --git a/doc/snippets/simple.qml b/doc/snippets/simple.qml
index 8f2b2bf..ea0eb75 100644
--- a/doc/snippets/simple.qml
+++ b/doc/snippets/simple.qml
@@ -1,6 +1,44 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Enginio Qt Client Library.
+**
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+****************************************************************************/
 
 import QtQuick 2.0
+//! [import]
 import Enginio 1.0
+//! [import]
 
 Rectangle {
     //! [client]
diff --git a/src/enginio_client/enginioclient.cpp b/src/enginio_client/enginioclient.cpp
index 871be8f..238409a 100644
--- a/src/enginio_client/enginioclient.cpp
+++ b/src/enginio_client/enginioclient.cpp
@@ -63,7 +63,7 @@
 
   The \l backendId and \l backendSecret are required for Engino to work.
   Once the client is set up you can use it to make queries to the backend
-  or use higher level API such as \l EnginioModel.
+  or use higher level API such as \l {EnginioModelCpp}{EnginioModel}.
 */
 
 /*!
@@ -418,9 +418,13 @@ void EnginioClient::setIdentity(EnginioIdentity *identity)
   Stores a \a file attached to an \a object in Enginio.
 
   Each uploaded file needs to be associated with an object in the database.
-  If there is no association, the file will eventually get deleted.
-  When an object which had a file associated gets deleted, the file will
-  automatically be deleted as well.
+
+  \snippet files.qml upload
+
+  Note: There is no need to directly delete files.
+  Instead when the object that contains the link to the file gets deleted,
+  the file will automatically be deleted as well.
+
 */
 EnginioReply* EnginioClient::uploadFile(const QJsonObject &object, const QUrl &file)
 {
@@ -433,6 +437,11 @@ EnginioReply* EnginioClient::uploadFile(const QJsonObject &object, const QUrl &f
     return ereply;
 }
 
+/*!
+  \brief Download a file stored in Enginio
+
+  \snippet files.qml download
+*/
 EnginioReply* EnginioClient::downloadFile(const QJsonObject &object)
 {
     Q_D(EnginioClient);
diff --git a/src/enginio_client/enginiomodel.cpp b/src/enginio_client/enginiomodel.cpp
index 2e16116..b40f02a 100644
--- a/src/enginio_client/enginiomodel.cpp
+++ b/src/enginio_client/enginiomodel.cpp
@@ -413,8 +413,10 @@ const int EnginioModelPrivate::IncrementalModelUpdate = -2;
   \class EnginioModel
   \inmodule enginio-qt
   \ingroup enginio-client
+  \target EnginioModelCpp
   \brief EnginioModel represents data from Enginio as a \l QAbstractListModel.
-  \mainclass
+
+  For the QML version of this class see \l {EnginioModelQml}{EnginioModel (QML)}
 */
 
 /*!
diff --git a/src/enginio_plugin/enginioplugin.cpp b/src/enginio_plugin/enginioplugin.cpp
index 65877a1..36a9076 100644
--- a/src/enginio_plugin/enginioplugin.cpp
+++ b/src/enginio_plugin/enginioplugin.cpp
@@ -57,15 +57,8 @@
  */
 
 
-/*!
- * \qmltype Error
- * \instantiates EnginioError
- * \inqmlmodule enginio-plugin
- * \brief Used to describe errors that occur during Enginio operations
- */
-
-/*!
- * \qmlproperty enumeration Error::error
+/* FIXME if needed
+ * \qmlproperty enumeration EnginioReply::errorCode
  * \list
  * \li Error.NoError - No errors.
  * \li Error.UnknownError - Something went wrong but we don't know what.
@@ -75,7 +68,7 @@
  * \endlist
  */
 
-/*!
+/*
  * \qmltype Acl
  * \instantiates EnginioAcl
  * \inqmlmodule enginio-plugin
@@ -107,7 +100,7 @@
  * value is \c {{ "id": "*", "objectType": "aclSubject" }}.
  */
 
-/*!
+/*
  * \qmlproperty enumeration Acl::Permission
  * \list
  * \li Acl.ReadPermission - Permission to read object data
@@ -118,26 +111,6 @@
  * \endlist
  */
 
-/*!
- * \qmlproperty object Acl::readPermissions
- * List of subjects that have "read" permission.
- */
-
-/*!
- * \qmlproperty object Acl::updatePermissions
- * List of subjects that have "update" permission.
- */
-
-/*!
- * \qmlproperty object Acl::deletePermissions
- * List of subjects that have "delete" permission.
- */
-
-/*!
- * \qmlproperty object Acl::adminPermissions
- * List of subjects that have "admin" permission.
- */
-
 QQmlEngine *g_qmlEngine = 0;
 
 class EnginioNetworkAccessManagerFactory: public QQmlNetworkAccessManagerFactory
diff --git a/src/enginio_plugin/enginioqmlclient.cpp b/src/enginio_plugin/enginioqmlclient.cpp
index 3c30b25..83270c4 100644
--- a/src/enginio_plugin/enginioqmlclient.cpp
+++ b/src/enginio_plugin/enginioqmlclient.cpp
@@ -49,7 +49,9 @@
   \inqmlmodule enginio-plugin
   \ingroup engino-qml
 
-  \brief Enginio client inteface to access the service
+  \brief client interface to access Enginio
+
+  \snippet simple.qml import
 
   Enginio is the heart of the QML API for Enginio.
   It is used for all communication with the Enginio backend.
diff --git a/src/enginio_plugin/enginioqmlmodel.cpp b/src/enginio_plugin/enginioqmlmodel.cpp
index 89cbc1d..ce991c6 100644
--- a/src/enginio_plugin/enginioqmlmodel.cpp
+++ b/src/enginio_plugin/enginioqmlmodel.cpp
@@ -37,6 +37,35 @@
 
 #include "enginioqmlmodel.h"
 
+/*!
+  \qmltype EnginioModel
+  \instantiates EnginioQmlModel
+  \inqmlmodule enginio-plugin
+  \ingroup engino-qml
+  \target EnginioModelQml
+
+  \brief Makes accessing collections of objects easy
+
+  The query property of the model takes a JSON object.
+
+  To get a model of each object of type "objects.city" use:
+  \snippet models.qml model
+
+  It is then possible to use a regular Qt Quick ListView
+  to display the list of cities that the backend contains.
+  \snippet models.qml view
+  Note that the properties of the objects can be directly accessed.
+  In this example, we have the type "objects.city" in the backend
+  with two properties: "name" and "population".
+
+  The model supports several function to modify the data, for example it is
+  easy to add another city to the backend by appending it:
+  \snippet models.qml append
+
+  The QML version of EnginioModel supports the same functionality as the C++ version.
+  \l {EnginioModelCpp}{EnginioModel C++}
+*/
+
 EnginioQmlModel::EnginioQmlModel(QObject *parent)
     : EnginioModel(parent)
 {