Release v1.1

commschamp · Mar 25, 2019 · e4f7b19 · e4f7b19
2 parents 503b0e5 + 0e94f05
commit e4f7b19
Show file tree

Hide file tree

Showing 21 changed files with 48 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Introduction
 This document contains specification of **D**omain **S**pecific **L**anguage (DSL),
-called **CommsDSL**, for [comms_champion](https://github.com/arobenko/comms_champion) ecosystem,
+called **CommsDSL**, for [CommsChampion Ecosystem](https://arobenko.github.io/cc),
 used to define custom binary protocols. The defined schema files are intended
 to be parsed and used by [commsdsl](https://github.com/arobenko/commsdsl) library and code
 generation application(s).

diff --git a/appendix/checksum.md b/appendix/checksum.md
@@ -6,7 +6,7 @@ for detailed description.
 |Property Name|Allowed type / value|DSL Version|Required|Default Value|Description|
 |:-----------:|:------------------:|:---------:|:------:|:-----------:|-----------|
 |**alg**|"sum", "crc-ccitt", "crc-16", "crc-32", "custom"|1|yes||Checksum calculation algorithm.|
-|**algName**|[name](../intro/names.md) string|1|no (unless **alg** is **custom**||Name of the custom algorithm. Applicable only if **alg="custom"**.|
+|**algName**|[name](../intro/names.md) string|1|no (unless **alg** is **custom**)||Name of the custom algorithm. Applicable only if **alg="custom"**.|
 |**from**|[name](../intro/names.md) string|1|yes (only if **until** is not specified)||Name of the frame layer, from which the checksum calculation starts.|
 |**until**|[name](../intro/names.md) string|1|yes (only if **from** is not specified)||Name of the frame layer, until (and including) which the checksum calculation is executed.|
 |**verifyBeforeRead**|[bool](../intro/boolean.md)|1|no|false|Perform checksum verification without reading values of other layers.|

diff --git a/appendix/float.md b/appendix/float.md
@@ -13,7 +13,7 @@ for detailed description.
 |**validValue**|floating point value, **nan**, **inf**, **-inf**|1|no||Valid value.|
 |**validMin**|floating point value|1|no||Valid minimal value. All the numbers above it are considered to be valid.|
 |**validMax**|floating point value|1|no||Valid maximal value. All the numbers below it are considered to be valid.|
-|**validCheckVersion**|[bool](../intro/boolean.md)|1|no|false|Mark all the range of existing FP values to be valid, excluding **nan**, **inf**, and **-inf**.|
+|**validFullRange**|[bool](../intro/boolean.md)|1|no|false|Mark all the range of existing FP values to be valid, excluding **nan**, **inf**, and **-inf**.|
 |**validCheckVersion**|[bool](../intro/boolean.md)|1|no|false|Take into account protocol version when generating code for field's value validity check.|
 |**displayDecimals**|[numeric](../intro/numeric.md)|1|no|0|Indicates to GUI analysis how many digits need to be displayed after the fraction point.|
 

diff --git a/appendix/list.md b/appendix/list.md
@@ -9,7 +9,7 @@ for detailed description.
 |**count**|[unsigned](../intro/numeric.md)|1|no|0|Fixed number of elements in the list. Cannot be used tegether with **lengthPrefix** or **countPrefix**.|
 |**countPrefix**|[field](../fields/fields.md) or [reference](../intro/references.md)|1|no||Prefix field containing number of elements in the list. Cannot be used tegether with **count** or **lengthPrefix**.|
 |**lengthPrefix**|[field](../fields/fields.md) or [reference](../intro/references.md)|1|no||Prefix field containing serialization length of the list. Cannot be used tegether with **count** or **countPrefix**.|
-|**elemLengthPrefix**|[field](../fields/fields.md)|1|no||Prefix field containing serialization length of the list element.|
+|**elemLengthPrefix**|[field](../fields/fields.md)|1|no||Prefix field containing serialization length of the list **element**.|
 |**elemFixedLength**|[bool](../intro/boolean.md)|1|no|false|Indication of whether list has and will allways have fixed length element, so **elemLengthPrefix** prefixes only the first element and not the rest.|
 
 

diff --git a/appendix/units.md b/appendix/units.md
@@ -45,7 +45,7 @@ The tables below contain lists of available units.
 |Hertz|"hz", "hertz"|
 |Kilohertz|"khz", "kilohertz"|
 |Megahertz|"mhz", "megahertz"|
-|Gigahertz|"ghz""gigahertz"|
+|Gigahertz|"ghz", "gigahertz"|
 
 #### Angle Units
 |Units Name|Accepted Values (case insensitive)|

diff --git a/fields/bundle.md b/fields/bundle.md
@@ -51,9 +51,9 @@ of the **&lt;bundle&gt;**, then all the members must be wrapped in
 ```
 
 #### Reusing Other Bundle
-Like any other field **&lt;bundle&gt;** supports **reuse** of any other **&lt;bundle&gt;**.
+Like any other field, **&lt;bundle&gt;** supports **reuse** of any other **&lt;bundle&gt;**.
 Such reuse copies all the fields from original **&lt;bundle&gt;** in addition
-to all the properties. Any new defined member field gets appended to the copied ones.
+to all the properties. Any new defined member field gets **appended** to the copied ones.
 ```
 <?xml version="1.0" encoding="UTF-8"?>
 <schema name="MyProtocol" endian="big">

diff --git a/fields/common.md b/fields/common.md
@@ -39,7 +39,7 @@ generated class. The [property](../intro/properties.md) is **description**.
 #### Reusing Other Fields
 Sometimes two different fields are very similar, but differ in one particular
 aspect. **CommsDSL** allows copying all the properties from previously defined
-field and change value of some properties after the copy. For example:
+field (using **reuse** property) and change some of them after the copy. For example:
 
 ```
 <?xml version="1.0" encoding="UTF-8"?>
@@ -80,7 +80,7 @@ the [name](../intro/names.md).
 ```
 
 If **displayName** is not specified, the code generator must use value of property
-**name** instead. In order to force empty name to display, use "_" (underscore).
+**name** instead. In order to force empty **displayName**, use "_" (underscore) value.
 ```
 <?xml version="1.0" encoding="UTF-8"?>
 <schema ...>
@@ -90,15 +90,31 @@ If **displayName** is not specified, the code generator must use value of proper
 </schema>
 ```
 
-The values of some fields may be controlled by other fields. In this case, it
+Sometimes the values of some fields may be controlled by other fields. In this case, it
 could be wise to disable manual update of such fields. To enable/disable such
 behavior use **displayReadOnly** property with [boolean](../intro/boolean.md)
 value.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <fields>
+        <int name="SomeIntField" displayReadOnly="true" ... />
+    </fields>
+</schema>
+```
 
-Sometimes, it can be desirable to completely hide some field 
+Also sometimes it can be desirable to completely hide some field 
 from being displayed in the protocol analysis GUI application. In this case
 use **displayHidden** property with [boolean](../intro/boolean.md)
 value.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <fields>
+        <int name="SomeIntField" displayHidden="true" ... />
+    </fields>
+</schema>
+```
 
 #### Versioning
 **CommsDSL** allows providing an information in what version the field was added

diff --git a/fields/enum.md b/fields/enum.md
@@ -31,7 +31,7 @@ values are:
 ```
 The variable length types are encoded using **Base-128** form, such as
 [LEB128](https://en.wikipedia.org/wiki/LEB128) for *little* endian or similar for
-big endian.
+*big* endian.
 
 #### Valid Values
 All the valid values must be listed as **&lt;validValue&gt;** child of the 
@@ -113,7 +113,7 @@ default endian value with extra **endian** property.
 
 #### Serialization Length
 The [underlying type](#underlying-type) dictates the serialization length
-of the **&lt;enum&gt;** field. However there may be protocols, that limit serialization
+of the **&lt;enum&gt;** field. However, there may be protocols that limit serialization
 length of the field to non-standard lengths, such as **3** bytes. In this case
 use **length** property to specify custom serialization length.
 ```
@@ -159,8 +159,8 @@ In this case the serialization length may be specified in bits using **bitLength
 
 #### Hex Assignment
 The code generator is expected to generate appropriate **enum** types using
-decimal values assigned to enumeration names. However, some protocols may list 
-valid values using hexadecimal format. To make the reading of the generated code
+**decimal** values assigned to enumeration names. However, some protocol specifications may list 
+valid values using **hexadecimal** format. To make the reading of the generated code
 more convenient, use **hexAssign** [property](../intro/properties.md) with
 [boolean](../intro/boolean.md) value to force code generator make the assignments
 using hexadecimal values.
@@ -197,7 +197,7 @@ enum class SomeEnumFieldVal
 
 #### Allow Non-Unique Values
 By default, non-unqiue values are not allowed, the code generator must report
-an error if two different **&lt;validValue&gt;**-es use the same value of **val**
+an error if two different **&lt;validValue&gt;**-es use the same value of the **val**
 property. It is done as protection against copy-paste errors. However,
 **CommsDSL** allows usage of non-unique values in case **nonUniqueAllowed** 
 [property](../intro/properties.md) has been set to **true**.

diff --git a/fields/fields.md b/fields/fields.md
@@ -24,7 +24,7 @@ It can also be defined as a member of a message.
 Field that is defined as a child of **&lt;fields&gt;** node of the 
 [&lt;schema&gt;](../intro/schema_def.md) or 
 [&lt;ns&gt;](../intro/namespaces.md) can be referenced by other fields to avoid
-definition duplication.
+duplication of the same definition.
 ```
 <?xml version="1.0" encoding="UTF-8"?>
 <schema ...>

diff --git a/fields/int.md b/fields/int.md
@@ -28,7 +28,7 @@ values are:
 ```
 The variable length types are encoded using **Base-128** form, such as
 [LEB128](https://en.wikipedia.org/wiki/LEB128) for *little* endian or similar for
-big endian.
+*big* endian.
 
 #### Special Values
 Some protocol may assign a special meaning for some values. For example, some

diff --git a/fields/list.md b/fields/list.md
@@ -242,7 +242,7 @@ length. **CommsDSL** supports such lists with **elemFixedLength**
     </fields>
 </schema>
 ```
-The code generator must report an error when element of such list, 
-with **elemFixedLength** property set to **true**, has variable length.
+The code generator must report an error when element of such list 
+(with **elemFixedLength** property set to **true**) has variable length.
 
 Use [properties table](../appendix/list.md) for future references.
diff --git a/fields/set.md b/fields/set.md
@@ -128,7 +128,7 @@ to **0xfe** when default constructed.
 
 
 #### Reserved Bits
-All the bits that weren't listed as **&lt;bit&gt;** XML child element
+All the bits that aren't listed as **&lt;bit&gt;** XML child elements
 are considered to be reserved. By default every reserved bit is expected to be 
 zeroed when field is checked to have a valid value. Such expectation can be changed using
 **reservedValue** property.

diff --git a/frames/checksum.md b/frames/checksum.md
@@ -70,7 +70,7 @@ to locate the required external implementation file and use appropriate
 class / function name when the calculation functionality needs to be invoked.
 
 #### Calculation Area
-The **custom** layer definition must also specify the layers, data of which is
+The **checksum** layer definition must also specify the layers, data of which is
 used to calculate the checksum. It is done using **from** property that is
 expected to specify name of the layer where checksum calculation starts.
 ```

diff --git a/frames/custom.md b/frames/custom.md
@@ -48,9 +48,6 @@ whole field to be dedicated to storage of the numeric ID. In such case
                 </set>
             </bitfield>
         </custom>
-        <id name="Id">
-            ...  
-        </id>
         <payload name="Data" />
     </frame>
 </schema>

diff --git a/frames/frames.md b/frames/frames.md
@@ -78,7 +78,7 @@ Available layers are:
 - [&lt;checksum&gt;](checksum.md) - Checksum.
 - [&lt;value&gt;](value.md) - Extra value, usually to be assigned to one of the
 [&lt;interface&gt;](../interfaces/interfaces.md) fields.
-- [&lt;custom&gt;](custom.md) - Any other custom layer, not provided by **CommsDSL**. 
+- [&lt;custom&gt;](custom.md) - Any other custom layer, not defined by **CommsDSL**. 
 
 If there is any other [property](../intro/properties.md) defined as XML child
 of the **&lt;frame&gt;**, then all the layers must be wrapped in 
@@ -96,7 +96,7 @@ of the **&lt;frame&gt;**, then all the layers must be wrapped in
 </schema>
 ```
 
-All this layers have [common](common.md) as well as their own specific set of 
+All these layers have [common](common.md) as well as their own specific set of 
 properties.
 
 Use [properties table](../appendix/frame.md) for future references.
diff --git a/frames/value.md b/frames/value.md
@@ -102,7 +102,7 @@ must be the same for all the listed interfaces.
 There are protocols that don't report protocol version in their transport
 framing. Instead, they use some special "connection" message that report
 protocol version. As the result, all subsequent messages must adhere to the
-reported protocol. The **CommsDSL** resolves this problem by defining 
+reported version. The **CommsDSL** resolves this problem by defining 
 **pseudo** **&lt;value&gt;** layer using **pseudo** [property](../intro/properties.md)
 with [boolean](../intro/boolean.md) value. The field of the pseudo **&lt;value&gt;** layer
 does not get serialized. However, the code generator must allow external

diff --git a/intro/properties.md b/intro/properties.md
@@ -2,8 +2,8 @@
 Almost every element in **CommsDSL** has one or more properties, such as **name**.
 Any property can be defined using multiple ways. In can be useful when an
 element has too many properties to specify in a single line for a convenient
-reading. Any of the described below supported ways of defining a single property
-can be used for any element in the schema.
+reading. **Any** of the described below supported ways of defining a single property
+can be used for **any** element in the schema.
 
 The property can be defined as an XML attribute.
 ```

diff --git a/intro/protocol_versioning.md b/intro/protocol_versioning.md
@@ -26,7 +26,7 @@ For example:
     </message>
 </schema>
 ```
-In the example above field **F2** was introduced in version 2. The field **F3**
+In the example above the field **F2** was introduced in version 2. The field **F3**
 was introduced in version 3, but deprecated and removed in version 4.
 
 All these version numbers in the schema definition allow generation of proper version checks

diff --git a/intro/references.md b/intro/references.md
@@ -21,7 +21,7 @@ circular references.
     </message>
 </schema>
 ```
-When referencing a field or a value from a namespace (any namespace, not just
+When referencing a field or a value defined in a namespace (any namespace, not just
 different one), the former must be prefixed with a namespace(s) name(s) 
 separated by a **.** (dot).
 ```

diff --git a/intro/version.md b/intro/version.md
@@ -1,5 +1,5 @@
 ## Version
-Current version of this document is **1.0**
+Current version of this document is **1.1**
 
 This document is versioned using [Semantic Versioning](https://semver.org/) 
 without **MAJOR** number (in intension not to have any non-backward compatible changes).

diff --git a/schema/schema.md b/schema/schema.md
@@ -74,8 +74,8 @@ For example version **1.5** can be defined and used throughout the schema as **0
 #### DSL Version
 As this specification evolves over time it can introduce new properties or
 other elements. It is possible to specify the version of the **DSL** as the schema's
-property. If code generator expects earlier version of the schema it is expected
-to report an error (or at least a warning). 
+property. If code generator expects earlier version of the schema it should
+report an error (or at least a warning). 
 
 The DSL version is specified using **dslVersion** property with unsigned integral
 value. Defaults to **0**, which means any version of code generator will try to