updated extending and grammar documentation

2 files changed, 122 insertions, 14 deletions

diff --git a/docs/extending.rst b/docs/extending.rst
index dc42cb8..042f094 100644
--- a/docs/extending.rst
+++ b/docs/extending.rst
@@ -1,6 +1,6 @@
-***************
-Extending QFace
-***************
+*********
+Extending
+*********
 
 QFace is easy to use and easy to extend. Your generator is just a small python
 script using the qface library.
@@ -75,7 +75,7 @@ The `RuleGenerator` allows you to extract the documentation rules into an extern
         generator = RuleGenerator(search_path=here/'templates', destination=output)
         generator.process_rules(here/'docs.yaml', system)
 
-The rules document is divided into several targets. Each target can have an own destination. A target is typical for example and app, client, server. Each target can have rules for the different symbols (system, module, interface, struct, enum). An each rule finally consists of a destination modifier, additional context and a documents collection.
+The rules document is divided into several targets. Each target can have an own destination. A target is typical for example and `app`, `client` or `server`. Each target can have rules for the different symbols (system, module, interface, struct, enum). An each rule finally consists of a destination modifier, additional context and a documents collection.
 
 .. code-block:: python
 
@@ -126,14 +126,14 @@ The rule generator adds the ``dst``, ``project`` as also the corresponding symbo
 
 .. rubric:: Features
 
-The rules document allows to conditional write files based on a feature set. The feature set must be a set of tags indicating the features which will then be checked in the ``when`` section of a rule.
+The rules document allows to conditional write files based on a feature set. The feature set must be a set of tags indicating the features which will then be checked in the ``when`` section of a rule. The ``when`` tag needs to be a list of feature switched.
 
 The features are passed to the generator in your custom generator code. The existence of a feature tells the rules engine to check if a ``when`` section exists conditionally execute this rule.
 
 .. code-block:: yaml
 
     plugin:
-        when: plugin_enabled
+        when: [plugin_enabled]
         destination: '{{dst}}/plugin'
         module:
             ...
@@ -157,3 +157,27 @@ Documents can be marked as preserved to prevent them to be overwritten when the
                 - '{{interface|lower}}.cpp'
 
 In the example above the two interface documents will not be overwritten during a second generator call and can be edited by the user.
+
+.. rubric:: Destination and Source
+
+The ``destination`` tag allows you to specify a prefix for the target destination of the document. It should always contain the ``{{dst}}`` variable to be placed inside the project folder.
+
+The ``source`` tag specifies a prefix for the templates resolving. If the template name starts with a ``/`` the prefix will be ignored.
+
+Destination and source tags are allowed on the target level as also on each system, module and other symbol levels. A tag on a parent symbol will be the default for the child symbols.
+
+.. rubric:: Implicit symbol hierarchy
+
+This is the implicit logical hierarchy taken into account:
+
+.. code-block:: xml
+
+    <target>
+        <system>
+            <module>
+                <interface>
+                <struct>
+                <enum>
+
+Typical you place the destination prefix on the module level if your destination depends on the module symbol. For generic templates you would place the destination on the system level. On the system level you can not use child symbols (such as the module) as at this time these symbols are not known yet.
+
diff --git a/docs/grammar.rst b/docs/grammar.rst
index ac6bf02..a8048ea 100644
--- a/docs/grammar.rst
+++ b/docs/grammar.rst
@@ -2,7 +2,7 @@
 Grammar
 =======
 
-QFace (Qt interface language) is an Interface Description Languge (IDL). While it is primarily designed to define an interface between Qt, QML and C++, it is intended to be flexible enough also to be used in other contexts.
+QFace (Qt interface language) is an Interface Description Language (IDL). While it is primarily designed to define an interface between Qt, QML and C++, it is intended to be flexible enough also to be used in other contexts.
 
 The grammar of QFace is well defined and is based on the concepts of modules as larger collection of information.
 
@@ -60,20 +60,104 @@ An interface is a collection of properties, operation and signals. Properties ca
         signal error(string message);
     }
 
+QFace allows to extends interfaces using the ``extends`` keyword after the interface name.
+
+.. code-block:: js
+
+    interface Station {
+        void reset();
+        signal error(string message);
+    }
+
+    interface WeatherStation extends Station {
+        real temperature;
+    }
+
+.. note::
+
+    For the sake of simplicity as an API designer you should carefully evaluate if this is required. The typical way in QFace to allow extension is normally to write your own code-generator and use type annotations.
+
+
+    .. code-block:: js
+
+        @station
+        interface WeatherStation {
+            real temperature;
+        }
+
+    The API reader does not need to know the internals of the API. The station behavior would be automatically attached by the custom generator.
+
+
+
 Struct
 ======
 
+The struct resembles a data container. It consist of a set of fields where each field has a data type and a name.
+
+.. code-block:: js
+
+    struct Error {
+        string message;
+        int code;
+    };
+
+Structs can also be nested. A struct can be used everywhere where a type can be used.
+
+.. code-block:: js
+
+    interface WeatherStation {
+        real temperature;
+        Error lastError;
+        void reset();
+        signal error(Error error);
+    }
+
+
+
 Enum/Flag
 =========
 
-Types
------
+An enum and flag is an enumeration type. The value of each member is automatically assigned if missing.
+
+.. code-block:: js
+
+    enum State {
+        Null,
+        Loading,
+        Ready,
+        Error
+    }
+
+The value assignment for the enum type is sequential beginning from 0. To specify the exact value you can assign a value to the member.
 
-Types are either local and can be references simply by its name, or they are from external module in this case they need to be referenced with the fully qualified name (``module + '.' + name``). A type can be an interface, struct, enum or flag.
+.. code-block:: js
+
+    enum State {
+        Null = 0,
+        Loading = 1,
+        Ready = 2,
+        Error = 3
+    }
+
+The flag type defines an enumeration type where these different values are treated as a bit mask. The values are in the sequence of the 2^n.
+
+.. code-block:: js
+
+    flag Cell {
+        Null,
+        Box,
+        Wall,
+        Figure
+    }
+
+
+
+Types
+=====
 
-A module consist of either one or more interfaces, structs and enums/flags. They can come in any number or combination. The interface is the only type which can contain operations and signals. The struct is merely a container to transport structured data. An enum/flag allows the user to encode information used inside the struct or interface as datatype.
+Types are either local and can be references simply by its name, or they are from external module in this case they need to be referenced with the fully qualified name (``<module>.<symbol>``). A type can be an interface, struct, enum or flag. It is also possible to reference the inner members of the symbols with the fragment syntax (``<module>.<symbol>#<fragment>``).
 
-The QFace does not allow to extend interfaces. It is by design kept simple.
+A module consist of either one or more interfaces, structs and enums/flags. They can come in any number or combination. The interface is the only type which can contain properties, operations and signals. The struct is merely a container to transport structured data. An enum/flag allows the user to encode information used inside the struct or interface as data-type.
 
 Below is an example of a QFace file.
 
@@ -153,7 +237,7 @@ More information on annotations can be found in the annotations chapter.
 Comments
 ========
 
-Comments use the JavaDoc convention of using an `@` sign as prefix with the keyword followed by the required paramters.
+Comments use the JavaDoc convention of using an `@` sign as prefix with the keyword followed by the required parameters.
 
 .. code-block::java
 
@@ -163,6 +247,6 @@ Comments use the JavaDoc convention of using an `@` sign as prefix with the keyw
 
 Currently only brief, description, see and deprecated are supported doc tags.
 
-The QtCPP builtin generator generates valid Qt documentation out of these comments.
+The QtCPP built-in generator generates valid Qt documentation out of these comments.