described some design decision for the QtCPP generator

1 files changed, 25 insertions, 2 deletions

diff --git a/docs/qtcpp.rst b/docs/qtcpp.rst
index bc62795..7a60f3c 100644
--- a/docs/qtcpp.rst
+++ b/docs/qtcpp.rst
@@ -31,7 +31,7 @@ For example an QFace document like this
     }
 
 
-The QTCPP generator will generate all CPP code including the plugin code and project files. Additional it will generate an empy simulation stub.
+The QTCPP generator will generate all CPP code including the plugin code and project files. Additional it will generate an empty simulation stub.
 
 In QML you would now be able to write the following code.
 
@@ -88,7 +88,27 @@ For each module the generator creates the qmake project files, the plugin code t
 
 An base implementation of the interface is generated in the private folder. A stub implementation derived form the abstract interface is generated and registered with the plugin.
 
-Each structure is generates as a Q_GADGET which behaves similar as a JS object on the QML side. The interface is by default registered as a normal qml type and contains the properties and methods as also signals as defined in the interface files.
+Each structure is generates as a Q_GADGET which behaves similar as a JS object on the QML side. The interface is by default registered as a normal QML type and contains the properties and methods as also signals as defined in the interface files.
+
+Design Decisions
+================
+
+* All properties generated are read only from QML
+
+    Writable properties on service objects are a cause of errors and confusion. It is very easy in the HMI stack to overwrite a binding property which writes to a service. It is better to offer a dedicated operation which does some work and triggers an operation update.
+
+* All models generated are read only from QML
+  
+    The data for a model is often stored inside another system (SQL DB, Remote, File System) and only a small subset of the data is actually in memory. Filtering, sorting or modifying the model data should be explicitly done using operations if supported by the user interface.
+
+* Data structures are exported as gadgets
+  
+    A Q_GADGET allows us to define a data structure and modify its contents. A gadget does not support signals, which means others are not notified about changes. This is the same behavior as for JS objects. Gadgets are copied from C++ to QML so there is no issue with memory management. QML has no means to create a gadget class, for this the module object contains a factory method for each structure.
+
+* Enums are collected into one module object
+
+    All enumerations are defined inside the module object. This allows us to remove the need to additional QObjects per enum. It has the drawback that each enum value should be unique in the module. The generator currently does not enforces this.
+
 
 Extending the Implementation
 ============================
@@ -99,4 +119,7 @@ In the interface document you are able to overwrite all setters and getters as a
 
 Besides the interface files also the plugin and project files are preserved, as it is expected that these files might be required to change. This may change in the future.
 
+
+
+