Release v2.1

commschamp · Sep 18, 2019 · a414b0e · a414b0e
2 parents 52d376c + 847a759
commit a414b0e
Show file tree

Hide file tree

Showing 4 changed files with 79 additions and 1 deletion.
diff --git a/appendix/float.md b/appendix/float.md
@@ -16,6 +16,9 @@ for detailed description.
 |**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.|
+|**nonUniqueSpecialsAllowed**|[bool](../intro/boolean.md)|2|no|false|Allow non unique **&lt;special&gt;**-s.|
+|**displaySpecials**|[bool](../intro/boolean.md)|2|no|true|Control displaying **&lt;special&gt;** values in analysis tools.|
+
 
 #### Properties of &lt;special&gt; Child Element of &lt;float&gt; Field
 |Property Name|Allowed type / value|DSL Version|Required|Default Value|Description|
@@ -25,4 +28,5 @@ for detailed description.
 |**description**|string|1|no||Human readable description of the value.|
 |**sinceVersion**|[unsigned](../intro/numeric.md)|1|no|0|Version of the protocol in which value was introduced.|
 |**deprecated**|[unsigned](../intro/numeric.md)|1|no|max unsigned|Version of the protocol in which value was deprecated.<br />Must be greater than value of **sinceVersion**.|
+|**displayName**|string|2|no||Name to display in various analysis tools.|
 
diff --git a/appendix/int.md b/appendix/int.md
@@ -21,6 +21,8 @@ for detailed description.
 |**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 tools to display this field as floating point value with specified number of digits after the fraction point.|
 |**displayOffset**|[numeric](../intro/numeric.md)|1|no|0|Indicates to GUI analysis tools to add specified offset value to a field's value when displaying it.|
+|**nonUniqueSpecialsAllowed**|[bool](../intro/boolean.md)|2|no|false|Allow non unique **&lt;special&gt;**-s.|
+|**displaySpecials**|[bool](../intro/boolean.md)|2|no|true|Control displaying **&lt;special&gt;** values in analysis tools.|
 
 #### Properties of &lt;special&gt; Child Element of &lt;int&gt; Field
 |Property Name|Allowed type / value|DSL Version|Required|Default Value|Description|
@@ -30,4 +32,5 @@ for detailed description.
 |**description**|string|1|no||Human readable description of the value.|
 |**sinceVersion**|[unsigned](../intro/numeric.md)|1|no|0|Version of the protocol in which value was introduced.|
 |**deprecated**|[unsigned](../intro/numeric.md)|1|no|max unsigned|Version of the protocol in which value was deprecated.<br />Must be greater than value of **sinceVersion**.|
+|**displayName**|string|2|no||Name to display in various analysis tools.|
 
diff --git a/fields/float.md b/fields/float.md
@@ -66,10 +66,29 @@ Every **&lt;special&gt;** has extra optional properties:
 - **description** - Extra description and documentation on how to use the value.
 - **sinceVersion** - Version of the protocol when the special name / meaning was introduced.
 - **deprecated** - Version of the protocol when the special name / meaning was deprecated.
+- **displayName** - Readable name to display for the special value in protocol debugging and visualization tools.
 
 All these extra properties are described in detail in 
 [Common Properties of Fields](common.md).
 
+By default, non-unqiue special values (different name for the same value) are 
+not allowed, the code generator must report
+an error if two different **&lt;special&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 **nonUniqueSpecialsAllowed** 
+[property](../intro/properties.md) has been set to **true**.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <fields>
+        <float name="SomeFloat" type="float" nonUniqueSpecialsAllowed="true">
+            <special name="S1" val="0.0" />
+            <special name="S2" val="0.0" />
+        </int>
+    </fields>
+</schema>
+```
+
 #### Default Value
 The default value of the **&lt;float&gt;** field when constructed can be specified
 using **defaultValue** property. If not specified, defaults to **0.0**.
@@ -279,4 +298,20 @@ with numeric value.
 If value of **displayDecimals** is **0**, then it is up to the GUI tool
 to choose how many digits after decimal point to display.
 
+When **&lt;special&gt;** values are specified the protocol analysis tools are 
+expected to display them next to actual numeric value of the field. The **displaySpecials**
+[property](../intro/properties.md) with [boolean](../intro/boolean.md) value
+is there to control this default behavior.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <fields>
+        <float name="SomeFloat" type="float" displaySpecials="false">
+            <special name="S1" val="0.0" />
+            <special name="S2" val="nan" />
+        </int>
+    </fields>
+</schema>
+```
+
 Use [properties table](../appendix/float.md) for future references.
diff --git a/fields/int.md b/fields/int.md
@@ -60,10 +60,29 @@ Every **&lt;special&gt;** has extra optional properties:
 - **description** - Extra description and documentation on how to use the value.
 - **sinceVersion** - Version of the protocol when the special name / meaning was introduced.
 - **deprecated** - Version of the protocol when the special name / meaning was deprecated.
+- **displayName** - Readable name to display for the special value in protocol debugging and visualization tools.
 
 All these extra properties are described in detail in 
 [Common Properties of Fields](common.md).
 
+By default, non-unqiue special values (different name for the same value) are 
+not allowed, the code generator must report
+an error if two different **&lt;special&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 **nonUniqueSpecialsAllowed** 
+[property](../intro/properties.md) has been set to **true**.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <fields>
+        <int name="SomeInt" type="uint8" nonUniqueSpecialsAllowed="true">
+            <special name="S1" val="0" />
+            <special name="S2" val="0" />
+        </int>
+    </fields>
+</schema>
+```
+
 #### Default Value
 The default value of the **&lt;int&gt;** field when constructed can be specified
 using **defaultValue** property. If not specified, defaults to **0**.
@@ -173,7 +192,7 @@ then serialize. The deserialization procedure is the opposite, first deserialize
 the non-negative value, and then subtract predefined offset to get the real value.
 
 For example, there is an integer field with expected valid values between 
--8,000,000 and +8,000,000. This range fits into 3 bytes, which are used to 
+`-8,000,000` and `+8,000,000`. This range fits into 3 bytes, which are used to 
 serialize such field. Such field is serialized using the
 following math:
 - Add 8,000,000 to the field's value to get non-negative number.
@@ -417,4 +436,21 @@ to display the value with serialization offset as well. It can be achieved using
 </schema>
 ```
 
+When **&lt;special&gt;** values are specified the protocol analysis tools are 
+expected to display them next to actual numeric value of the field. The **displaySpecials**
+[property](../intro/properties.md) with [boolean](../intro/boolean.md) value
+is there to control this default behavior.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <fields>
+        <int name="SomeInt" type="uint8" displaySpecials="false">
+            <special name="S1" val="0" />
+            <special name="S2" val="2" />
+        </int>
+    </fields>
+</schema>
+```
+
+
 Use [properties table](../appendix/int.md) for future references.