1 files changed, 92 insertions, 8 deletions
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.