Improve documentation (#77)

Fixed mostly spelling errors, but also phrasing and technical issues.

6 files changed, 43 insertions, 43 deletions

diff --git a/docs/annotations.rst b/docs/annotations.rst
index 1092f6e..73436c8 100644
--- a/docs/annotations.rst
+++ b/docs/annotations.rst
@@ -2,10 +2,10 @@
 Annotations
 ***********
 
-Annotations is a way to add meta information to your interface definition. It
+Annotations allow to add meta information to your interface definition. It
 is available to each symbol in the interface.
 
-Annotations allows an interface author to extend the existing interface with additional meta information, called tags, aka annotations. One or several annotations can precede a module, ``interface``, ``struct`` or ``enum``. They are also allowed before an ``operation``, ``property`` or ``signal``. Everywhere where a documentation comment is allowed you can also add annotations.
+With annotations an interface author can extend the existing interface with additional meta information, called tags, aka annotations. One or several annotations can precede a module, ``interface``, ``struct`` or ``enum``. They are also allowed before an ``operation``, ``property`` or ``signal``. Everywhere where a documentation comment is allowed you can also add annotations.
 
 An annotation looks like this
 
@@ -16,9 +16,9 @@ An annotation looks like this
     }
 
 
-An in code annotation precedes a symbol and it starts with an ``@`` sign. A symbol can have more than one one annotation line. Each line should be one individual annotation. The content is YAML content. All ``@`` signs preceding a symbol are collected and then evaluated using a YAML parser.
+An embedded annotation precedes a symbol and it starts with an ``@`` sign. A symbol can have more than one annotation line. Each line should be one individual annotation. The content is YAML content. All ``@`` signs preceding a symbol are collected and then evaluated using a YAML parser.
 
-For larger annotations you can use the external annotation document feature.
+For larger annotations you can use the external annotation document feature (see below).
 
 .. code-block:: python
 
@@ -63,12 +63,12 @@ On the root level should be a fully qualified name of a symbol. The symbol will
 Merging Annotations
 ===================
 
-The external annotations will be merged on top of the embedded annotations on per symbol base. Dictionaries will be merged. If a merge can not be done then the external document based annotations will override the embedded annotations.
+The external annotations will be merged on top of the embedded annotations per symbol. Dictionaries will be merged. If a merge can not be done then the external document based annotations will override the embedded annotations.
 
 Generators
 ==========
 
-The annotation are available later when navigating the domain model.
+Annotations are available later when navigating the domain model.
 
 .. code-block:: jinja2
 
diff --git a/docs/builtin.rst b/docs/builtin.rst
index a24f424..b0a339b 100644
--- a/docs/builtin.rst
+++ b/docs/builtin.rst
@@ -1,7 +1,7 @@
 Generator Examples
 ==================
 
-QFace does provide soem real world generators which are hosted as separated projects. Their purpose is merely to showcase how to write a code generator with QFace. They are working and complete examples of a general purpose generators.
+QFace does provide some real world generators which are hosted as separated projects. Their purpose is merely to showcase how to write a code generator with QFace. They are working and complete examples of general purpose generators.
 
 `qface-qtcpp`_
 
@@ -22,7 +22,7 @@ QFace does provide soem real world generators which are hosted as separated proj
     Hosted at: https://github.com/Pelagicore/qface-qtro
 
 
-From the QML user interface perspective the QtCPP and QtQML generators bth provide the same API and are interchangeable.
+From the QML user interface perspective the QtCPP and QtQML generators both provide the same API and are interchangeable.
 
 
 
diff --git a/docs/grammar.rst b/docs/grammar.rst
index cb73e8d..a4c2663 100644
--- a/docs/grammar.rst
+++ b/docs/grammar.rst
@@ -4,7 +4,7 @@ Grammar
 
 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.
+The grammar of QFace is well defined and is based on the concept of modules as larger collections of information.
 
 A module can have several interfaces, structs and/or enums/flags.
 
@@ -37,7 +37,7 @@ A QFace document always describes one module. Each document can contain one or m
 Module
 ======
 
-A module is identified name. A module should be normally a URI where all parts are lowercase (e.g. `entertainment.tuner`). A module may import other modules with the primary purpose being to ensure that dependencies are declared inside the QFace file.
+A module is identified by its name. A module should be normally a URI where all parts are lowercase (e.g. `entertainment.tuner`). A module may import other modules with the primary purpose being to ensure that dependencies are declared inside the QFace file.
 
 .. code-block:: js
 
@@ -50,7 +50,7 @@ A module is identified name. A module should be normally a URI where all parts a
 Interface
 =========
 
-An interface is a collection of properties, operation and signals. Properties carry data, whereas the operations normally modify the data. Signals are used to notify the user of changes.
+An interface is a collection of properties, operations and signals. Properties carry data, whereas the operations normally modify the data. Signals are used to notify the user of changes.
 
 .. code-block:: js
 
@@ -60,7 +60,7 @@ 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.
+QFace allows to extend interfaces using the ``extends`` keyword after the interface name.
 
 .. code-block:: js
 
@@ -75,12 +75,12 @@ QFace allows to extends interfaces using the ``extends`` keyword after the inter
 
 .. 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.
+    For the sake of simplicity, as an API designer you should carefully evaluate if this is required. The typical way in QFace to allow extensions is normally to write your own code-generator and use type annotations.
 
 
     .. code-block:: js
 
-        @station
+        @extends: Station
         interface WeatherStation {
             real temperature;
         }
@@ -139,7 +139,7 @@ The value assignment for the enum type is sequential beginning from 0. To specif
         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.
+The flag type defines an enumeration type where different values are treated as a bit mask. The values are in the sequence of the 2^n.
 
 .. code-block:: js
 
@@ -155,9 +155,9 @@ The flag type defines an enumeration type where these different values are treat
 Types
 =====
 
-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>``).
+Types are either local and can be referenced simply by their names, or they are from external modules. In the latter 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>``).
 
-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.
+A module consists 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.
 
@@ -234,14 +234,14 @@ A nested type is a complex type which nests another type. These are container ty
     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 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 chosen by the generator. This allows for example the generator 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.
+A model is a special type of a list. It should be able to stream (e.g. add/change/remove) the data and the changes should be reflected by a more advanced API. Also the data could in general grow infinitely and the generator should provide some form of pagination or window API. You should use a model if you expect the data it represents to grow in a way that it may influence the performance of your API.
 
 Annotations
 ===========
 
-Annotation allow the writer to add meta data to an interface document. It uses the `@` notation followed by valid YAML one line content.
+Annotations allow the writer to add meta data to an interface document. It uses the `@` notation followed by valid YAML one line content.
 
 .. code-block:: js
 
@@ -272,7 +272,7 @@ Default Values
 ==============
 
 QFace supports the assignment of default values to properties and struct fields. A default values is a text string
-passed onto the generator.
+passed to the generator.
 
 .. code-block:: js
 
@@ -285,5 +285,5 @@ passed onto the generator.
         string text = "NO DATA";
     }
 
-You can use quotes `'` or double-quotes `"` as a marker for text. There is no type check on qface side the 
-text-content is directly on to the generator.
+You can use quotes `'` or double-quotes `"` as a marker for text. There is no type check on QFace side. The
+text-content is directly passed to the generator.
diff --git a/docs/index.rst b/docs/index.rst
index ed5f38a..0212095 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,7 +4,7 @@ QFace
 
 QFace is a flexible API generator inspired by the Qt API idioms. It uses a common IDL format (called QFace interface document) to define an API. QFace is optimized to write a custom generator based on the common IDL format.
 
-There exists already several code generators for common use cases. These can be used as is or can be used as a base for a custom generator.
+Several code generators for common use cases have already been implemented. These can be used as is or can be used as a base for a custom generator.
 
 .. toctree::
    :maxdepth: 1
@@ -24,7 +24,7 @@ There exists already several code generators for common use cases. These can be
 Features
 ========
 
-The list fo features is plit between features which are based on the choosen IDL and features wich are provided by the generator itself.
+The list fo features is plit between features which are based on the chosen IDL and features which are provided by the generator itself.
 
 .. rubric:: IDL Features
 
@@ -47,7 +47,7 @@ The list fo features is plit between features which are based on the choosen IDL
 Quick Start
 ===========
 
-QFace is a generator framework and is bundled with several reference code generator.
+QFace is a generator framework and is bundled with several reference code generators.
 
 To install qface you need to have python3 installed and typically also pip3
 
@@ -73,7 +73,7 @@ and then
 Custom Generator
 ----------------
 
-For your own generator you need several ingredients. A QFace interface file here called "sample.qface" a small script which loads and parses the document. And one or more template files, which generate the resulting code.
+For your own generator you need several ingredients. A QFace interface file (here called "sample.qface"), a small script which loads and parses the document (generator.py) and one or more template files, used by the script to generate the resulting code.
 
 The QFace document could look like this
 
@@ -127,7 +127,7 @@ And a "org.example.txt" file named after the module should be generated.
 Bundled Generators
 ------------------
 
-QFace has some gnerators which are bundled with the QFace library. They live in their own reposiutories. These generators are documented in the repositories.
+QFace has some generators which are bundled with the QFace library. They live in their own repositories. These generators are documented in their respective repositories.
 
 .. rubric:: See Also
 
diff --git a/docs/motivation.rst b/docs/motivation.rst
index 2b54801..299c160 100644
--- a/docs/motivation.rst
+++ b/docs/motivation.rst
@@ -7,7 +7,7 @@ QFace is an attempt to establish one interface description language with an easy
 The IDL
 =======
 
-The IDL uses common API concept such as modules, interfaces, properties, structs and enums/flags. Additionally it knows about lists and models. A list is an array of primitive or complex types. A model is an indicator for large data sets which are typical used via a defined interface or via pagination.
+The IDL uses common API concept such as modules, interfaces, properties, structs and enums/flags. Additionally it knows about lists, maps and models. A list is an array of primitive or complex types. A map is an associative array of key/value pairs. A model is an indicator for large data sets which are typically used via a defined interface or via pagination.
 
 .. code-block:: js
 
@@ -41,48 +41,48 @@ Complex Types
 * Struct
 * Enum
 * Flag
-* Array
+* List
+* Map
 * Model
 
-The language as such does not provide any support for maps or dictionaries. The reason for not providing a map container type is that keys in dictionaries requires a hash which can not always be guaranteed to be available in complex types.
 
 Why another IDL
 ===============
 
-There exists many IDLs. Most of them are bound to a certain technology or library or are limited for a specific use. Only a few IDL exists which are independent from a technology. From these few which are known to the author none satisfied the requirement from the author to be Qt compatible and easy to use. Also the IDL should be easy to use and easy to be install and to be extendable. The unique mix of technologies used in QFace allows it to provide a solid stable IDL with a powerful generation framework.
+Many IDLs are already in existence. Most of them are bound to a certain technology or library or are limited for a specific use. Only a few IDLs exist which are independent from a technology. From these few which are known to the author none satisfied the requirement from the author to be Qt compatible and easy to use. Also the IDL should be easy to install and be extendable. The unique mix of technologies used in QFace allows it to provide a solid stable IDL with a powerful generation framework.
 
 
 Defining APIs
 =============
 
-There are many opinions how to define APIs and what is the best way. The porposal of QFace is that is many project find QFace useful and use the same IDL there will be a large set of generators and at the end APIs can be compared and unified also if they will be used with different technologies.
+There are many opinions how to define APIs and what the best way is. The idea of QFace is that many projects find it useful and use the same IDL. Consequently, there will be a large set of generators and finally APIs can be compared and unified also if they will be used with different technologies.
 
-Even inside on e technolgy there are often discussions about how an interface shall be coded. QFace allows the different parties to create their own generators based on the same API. Ideally at the end the knowledge how an interface shall be coded will reside in the provided generator.
+Even inside one technology there are often discussions about how an interface shall be coded. QFace allows the different parties to create their own generators based on the same API. Ideally at the end the knowledge how an interface shall be coded will reside in the provided generator.
 
 Large Projects
 ==============
 
-In larger projects there is the need to make available to QML a large set of operating services. It is less about defining new visual items in C++, more about creating an abstraction of a service and make it available to the HMI developer inside QML.
+In larger projects there is the need to make a large set of operating services available to QML. It is less about defining new visual items in C++, more about creating an abstraction of a service and make it available to the HMI developer inside QML.
 
-This can be a challenge when you create many of these plugins and in the middle of the project you figure out you have issues with your current design. Or if the customer in the next project wants to use a different HMI technology. All the knowledge is inside these plugins.
+This can be a challenge when you create many of these plugins and in the middle of the project you figure out that you have issues with your current design or if the customer in the next project wants to use a different HMI technology. All the knowledge is inside these plugins.
 
 With QFace these companies can be certain that QFace does not lock them into the HMI technology and smaller design issues can be fixed by fixing the generator.
 
 Remote Services
 ===============
 
-Some projects use network communication to communicate from the HMI to the services, which might run on a different process or event networked device. QFace was not designed for remote services as it does not define any storage types (e.g. int32, int16, int64), it  only knows an int and does not define how large the int shall be. For this QFace needs to rely on the author of the generators to have a defined protocol to exchange data.
+Some projects use network communication to communicate from the HMI to the services, which might run on a different process or even a networked device. QFace was not designed for remote services as it does not define any storage types (e.g. int32, int16, int64), it  only knows an int and does not define how large the int shall be. For this QFace needs to rely on the author of the generators to have a defined protocol to exchange data.
 
 Complex APIs
 ============
 
 QFace is purposely designed to have limited features. The goal is to make QFace easy to use with an easy to remember syntax so that you don't need to be an expert to write interface files.
 
-QFace does not suppot unions or extending from other interfaces or that a struct extends other structs. If you look for these features than QFace is probably the wrong choice.
+QFace does not support unions or structs that extend other structs. If you look for these features, QFace is probably the wrong choice.
 
 Limitations
 ===========
 
-Like other code generation tools, QFace is limited by how much information you can place inside your interface files. In such cases code generation might not make sense and QFace will also help.
+Like other code generation tools, QFace is limited by how much information you can place inside your interface files. In excessive cases code generation might not make sense and hence QFace will also not help.
 
-QFace allows you to use annotation which can add meta information to the interface files. But the generator needs to be designed to understand this meta information. Only the structure of these annotations are defined not the information they carry. Annotations might help to add information to an interface document to better control the code generation process.
+QFace allows you to use annotations which can add meta information to the interface files. But the generator needs to be designed to understand this meta information. Only the structure of these annotations are defined not the information they carry. Annotations might help to add information to an interface document to better control the code generation process.
diff --git a/docs/usage.rst b/docs/usage.rst
index 7105bfa..74a1714 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -9,7 +9,7 @@ QFace requires one or more IDL files as input file and a generator to produce ou
 
 .. figure:: qface_concept.jpg
 
-To use qface you need to write your own generator. A generatopr is a small python script which reads the qface document and write code using a generator.
+To use QFace you need to write your own generator. A generator is a small python script which reads the QFace document and writes code using template files.
 
 .. code-block:: python
 
@@ -51,7 +51,7 @@ The code generation is driven by a small script which iterates over the domain m
         generator.write('{{output}}/modules.csv', 'modules.csv', ctx)
 
 
-This script reads the input directory returns a system object form the domain model. This is used as the root object for the code generation inside the template language.
+This script reads the input directory and returns a system object from the domain model. This is used as the root object for the code generation inside the template language.
 
 .. code-block:: jinja
 
@@ -67,4 +67,4 @@ This script reads the input directory returns a system object form the domain mo
         {% endfor -%}
     {% endfor %}
 
-The template iterates over the domain objects and generates text which is written into a file. Using the generator write method ``generator.write(path, template, context)`` the output file path can also be specified using the template syntax .
+The template iterates over the domain objects and generates text which is written into the output file. Using the generator write method ``generator.write(path, template, context)`` the output file path can be specified.