From 170b6ca90740903c0bd3f56e803452beac1863ec Mon Sep 17 00:00:00 2001
From: Juergen Bocklage-Ryannel <juergen@ryannel.org>
Date: Wed, 7 Mar 2018 20:26:10 +0100
Subject: added section for language profiles and maps to the guide

---
 docs/extending.rst | 30 ++++++++++++++++++++++++++++++
 docs/grammar.rst   | 18 ++++++++++++++++++
 2 files changed, 48 insertions(+)

(limited to 'docs')

diff --git a/docs/extending.rst b/docs/extending.rst
index 5252ed0..910c086 100644
--- a/docs/extending.rst
+++ b/docs/extending.rst
@@ -195,3 +195,33 @@ See below for a simple example
     {% endwith %}
 
 Each tag in the JavaDoc styled comment, will be converted into a property of the object returned by `parse_doc`. All lines without a tag will be merged into the description tag.
+
+
+Language Profiles
+=================
+
+
+QFace supports the notion of profile. A profile is a set of features supported by the named profile. The intention of a profile is to make it easier for generator writers to stick to a limited set of language features, also if the overall language is evolving.
+
+Currently there exists three language profiles:
+
+* Micro - A limited set of languages features. The base profile. It does not allow importing of other modules or extending an interface, neither does it support maps.
+* Advanced - Builds upon micro and allows imports, maps, interface extension.
+* Full - Builds up on advanced and will also contain experimental language features.
+
+The current features defined are:
+- const oeprations
+- const properties
+- imports
+- maps
+- interface extensions
+
+The profiles and features are defined in the `qface.idl.profile` module.
+
+.. code-block:: py
+
+    from qface.generator import FileSystem
+    from qface.idl.profile import EProfile
+
+    system = FileSystem.parse(input=input, profile=EProfile.MICRO)
+
diff --git a/docs/grammar.rst b/docs/grammar.rst
index a8048ea..eb6546d 100644
--- a/docs/grammar.rst
+++ b/docs/grammar.rst
@@ -180,6 +180,8 @@ Below is an example of a QFace file.
 
         list<int> primitiveList;
         list<Station> complexList;
+        map<int> simpleMap;
+        map<Station> complexMap;
         model<int> primitiveModel;
         model<Station> complexModel;
     }
@@ -220,6 +222,22 @@ Below is an example of a QFace file.
     }
 
 
+
+Nested Types
+============
+
+A nested type is a complex type which nests another type. These are container types, e.g. list, map or model.
+
+.. code-block:: language
+
+    list<Color>  colors
+    map<Station> stations
+    model<WeatherInfo> weather
+
+A list is an array of the provided value type. A map specifies only the value type. The key-type should be generic (e.g. a string type) and can be freely choosen by the generator. This allows for example the geenrator to add an id to each structure and use it as a key in the map.
+
+A model is a special type of a list, it defines the model type can stream the data (e.g. add/change/remove) and the changes should be reflected by a more advanced API. Also the data could in general grow unlimited and the generator should provide some form of pagination or window API. You should use a model if you expect the data it represents can grow in a way it may influence the performance of your API.
+
 Annotations
 ===========
 
-- 
cgit v1.2.1