docs: Update according to review of PR #60

Signed-off-by: Gunnar Andersson <gunnar_dev@[email protected]>

docs/def-specification.stage2.m.md

@@ -4,7 +4,7 @@
 (C) 2022 - COVESA  
 (C) 2021 - Magnus Feuer  
 
-This document contains an introduction to the the Interface Exchange (IFEX)
+This document contains an introduction to the Interface Exchange (IFEX)
 framework and specification of the core Interface Description Language/Model
 (also known as ifex-idl and ifex-core).  IFEX is the name for the _technology_
 (language, tools, etc.) behind the Vehicle Service Catalog (VSC) project.

docs/static-general-description.md

@@ -63,13 +63,13 @@ Please note that in the text, "target-environment dependent", may sometimes be s
 
 ## Interface
 
-- Generally, Interface is a broad term.  In IFEX core IDL we concerned with functional software interfaces, nothing related to hardware, electrical or mechanical.
+- Generally, Interface is a broad term.  In IFEX core IDL we are concerned with functional software interfaces, nothing related to hardware, electrical or mechanical.
 - An IFEX Interface is like a specialization of the Namespace concept, but used specifically to group things that are intended to be the externally visible (a.k.a. public) interface of a software component that defines its interface using the IFEX file.
 - Design note: It would have been possible to generalize even further and to say that "an Interface is just a Namespace".  In that case, a layer would have been used to indicate which Namespace object(s) shall be considered one that holds the primary objects of our 'exported' interface.  But since the purpose of the IDL is primarily to define an interface it seems appropriate to give it special status by giving it its own keyword in the IDL itself.  Also, the nature of "visibility of objects" and "avoiding name clashes" (main reason for Namespace) is subtly different from the nature of "which objects do we consider being part of our outwardly displayed interface".
 - In this definition, the  Interface is not itself a Namespace (in terms of object visibility) but it must be defined within a Namespace.  All the Interface's objects belong to the parent Namespace of the Interface.
 - An Interface can contain all things a Namespace can contain, except another Interface (no nesting).
 - An IFEX **Interface** is often defined by a collection of **Methods**, but could also expose functionality through **Event**s and data **Properties**.  The interface might also include variables, constants, method-arguments, types, observable data-items and events that are required by the client using the interface.  That can be done for clarity, but from visibility standpoint it is identical to including them in the immediate parent Namespace.
-- The IFEX core IDL strives to usable in all areas of a computing system.  The interface definition therefore does not define details around communication hardware, implementation language, data-communication protocols, bit-encoding and in-memory layouts etc.  Such information is however added through supplementary information in the mappings and tools that consume the interface description.
+- The IFEX core IDL strives to be usable in all areas of a computing system.  The interface definition therefore does not define details around communication hardware, implementation language, data-communication protocols, bit-encoding and in-memory layouts etc.  Such information is however added through supplementary information in the mappings and tools that consume the interface description.
 - All Methods/Properties/Events defined or referred to by an Interface are required to be within the same Namespace, i.e. it is not possible to build an Interface by referring to Methods that have been defined in different Namespaces.
 
 ### Method
@@ -89,27 +89,27 @@ Please note that in the text, "target-environment dependent", may sometimes be s
 ### Event
 
 - An Event is a time-sensitive communication with _fire-and-forget_ behavior, sent between parts in the distributed system.
-- A IFEX Event can carry multiple pieces of data with it, each of which can use an arbitrary data type.
-- A IFEX Event definition looks similar to a Method but with some differences in definition and behavior:
+- An IFEX Event can carry multiple pieces of data with it, each of which can use an arbitrary data type.
+- An IFEX Event definition looks similar to a Method but with some differences in definition and behavior:
   - An Event has a name, and optionally a set of parameters that are distributed with the event, each having a name and a datatype.  This mimics a Method signature.  Just like a method, parameters are defined as **input parameters**. It is viewed from the perspective of the _receiver_ of the event.
   - An Event can **not** have a Return type, nor any out-parameters.
   - An Event may have **Error**s defined but with limited effect.  Since the expected behavior is "fire and forget", the usage of Error is likely to only be to report very fundamental errors, such as the network protocol returning an error because the connection was closed, etc.  (Note that such low-level Errors would normally not appear in a generic and reusable interface description, but in that case be added when specific deployment-details are layered on to the definition).
 - _Fire-and-forget_ expected behavior means that on the IFEX semantics level it is _not expected_ to be a guaranteed delivery.  It is in reality decided by the target environment mapping whether an Event is sent over a reliable or unreliable transport, but in either case, there is **no reply** defined for an Event.  When an interface is designed it shall use a **Method** if reliability is expected.  In the case of a Method, a return value would indicate that the information was received.
 
 **Avoiding event confusion:**
 
-- An IFEX **Event** is not a persistent data item, and thus has no built-in concepts of active-low/high, level or edge-trigger, rising/falling edge, etc. (other than what its name and documentation indicates\*\*).  It is to expressly indicate a particular thing "has happened".  It happened "at this point in time", and is communicated as nearly as possible to the time of the happening.
+- An IFEX **Event** is not a persistent data item, and thus has no built-in concepts of active-low/high, level or edge-trigger, rising/falling edge, etc. (other than what its name and documentation indicates).  It is there to expressly indicate a particular thing "has happened".  It happened "at this point in time", and is communicated as nearly as possible to the time of the happening.
 
 - An IFEX **Event** is a separate and _expressly defined_ object in the interface description. It should be used for something central to the "business-logic" of the interface.  It is not to be mixed up with lower level "happenings" in a system that do not need to be expressly defined.  Events shall not be confused with messages that are _automatically_ sent by some target environment directly, either that they are always done (hidden as part of that implementation) or  _as a result of_ the already encoded behavior of other objects already in the IDL.  
 
-    - The most obvious example is this:  In many systems, subscribing to changes of an observable data **Property** may trigger something that the target environment might call "update events", but those are a consequence of the behavior of the observable Property.   Assuming that the target-mapping is generating both sides of the communication, then these do not need explicit Event objects in the IDL itself.  It can sometimes be difficult to draw this distinction, but remember that if these low-level behaviors can be automatically generated during code-generation as a consequence of some object that is already in the interface (plus sometimes, some additional layered information), then it is not necessary to provide more information to the code-generators for them to succeed.  Those low-level mechanisms are normally decided by the particular data protocol or target environment and would then not be reusable in another context.  Since they are automatically generated from other objects (Property for example), there is no need to provide additional information in the IDL about them.  The strategy should be: Avoid overlapping definitions in the core IDL, and let the target environment mappings decide what the auto-generated result of that input information is (as long as it follows the _generally expected behavior_ described in this specification.   A Property is described as "observable" in the core IFEX IDL.  Most of the time, let the target mapping decide how that observability is implemented, and avoid modeling explicit events for that purpose.  That said, in certain cases, when auto-translating from another IDL description that already have explicit events of that nature, then it might not be possible to follow this guideline, but just try where possible to lift the interface level to objects with more built-in semantic meaning, such as Method and Property.
+    - The most obvious example is this:  In many systems, subscribing to changes of an observable data **Property** may trigger something that the target environment might call "update events", but those are a consequence of the behavior of the observable Property.   Assuming that the target-mapping is generating both sides of the communication, then these do not need explicit Event objects in the IDL itself.  It can sometimes be difficult to draw this distinction, but remember that if these low-level behaviors can be automatically generated during code-generation as a consequence of some object that is already in the interface (plus sometimes, some additional layered information), then it is not necessary to provide more information to the code-generators for them to succeed.  Those low-level mechanisms are normally decided by the particular data protocol or target environment and would therefore not be reusable in another context.  Since they are automatically generated from other objects (Property for example), there is no need to expressly define them in the fundamental Interface description.  The strategy should be: Avoid overlapping definitions in the core IDL, and let the target environment mappings decide what the auto-generated result of that input information is (as long as it follows the _generally expected behavior_ described in this specification.   A Property is described as "observable" in the core IFEX IDL.  Most of the time, let the target mapping decide how that observability is implemented, and avoid modeling explicit events for that purpose.  That said, in certain cases, when auto-translating an interface description from another IDL that already have explicit events encoded, then it might not be possible to follow this guideline, but just try where possible to lift the interface level to objects with more built-in semantic meaning, such as Method and Property.
 
-- \*\* Design tip:  If there is a need to model On/Off events, to avoid duplicating each one into two different Events -> give the event a single name and transfer a boolean as argument: FooState(bool) where the true/false value indicates the on/off state.  Another option might be to define an observable boolean data **Property** and use the target environment's Pub/Sub capability to get updates on its state.  (Depending on the details of the target environment, the latter might also give reliability guarantees that Events do not have).
+- Design tip:  If there is a need to model On/Off events, to avoid duplicating each one into two different Events -> give the event a single name and transfer a boolean as argument: FooState(bool) where the true/false value indicates the on/off state.  Another option might be to define an observable boolean data **Property** and use the target environment's Pub/Sub capability to get updates on its state.  (Depending on the details of the target environment, the latter might also give reliability guarantees that Events do not have).
 
-- Conceptually, an Event can be sent from client to server or from server to client(\*).
+- Conceptually, an Event can be sent from client to server or from server to client.
 (\*) TO CLARIFY: Shall the direction of an event be defined, and how?
 
-- \*\* If some events are to be transferred as a "broadcast" (from server to all clients) when other events would be addressed uniquely to particular client(s), then define this difference as extra information in a deployment model / target mapping.  It is not specified in the interface description.
+- If some events are to be transferred as a "broadcast" (from server to all clients) while other events would be addressed uniquely to particular client(s), then define this difference as extra information in a deployment model / target mapping.  It is not specified in the IFEX core IDL interface description.
 
 ### Property
 
@@ -140,7 +140,7 @@ Please note that in the text, "target-environment dependent", may sometimes be s
 
 - In all cases, an IFEX Method may define a Return Value type.  The return value can be defined for the interface description, without knowing the manner that the method will be invoked (e.g. the chosen communication protocol). IFEX-IDL-language has the unique feature of using the Return Value type to serve two different purposes in sync vs async situations:
 
-- As discussed, the details _may_ be target-environment dependent, but we can here define the _generally expected_ behavior of the return type in a system built from a IFEX interface:  
+- As discussed, the details _may_ be target-environment dependent, but we can here define the _generally expected_ behavior of the return type in a system built from an IFEX interface:  
   1. In the case of a blocking/synchronous call, the Return Value type is the value communicated _once_ after the operation completes.  
   2. In the case of a non-blocking/asynchronous call, the same defined Return Value type is also used with the difference that it _may_ be returned _multiple times_.  Using that behavior is optional and target-dependent, but if it is used then a target environment may choose to provide a regular stream of status updates while the method executes.  In each such update, a value is transferred that matches the defined Return Value type\*\*.  
   - It follows that only valid values of the Return Value type shall be returned.