From 0e94f05ac4597938a1d9851f6df1d50d087cf8ea Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Tue, 26 Mar 2019 09:28:06 +1000 Subject: [PATCH] Multiple fixes: typos, spelling, copy-paste errors, links. --- README.md | 2 +- appendix/checksum.md | 2 +- appendix/float.md | 2 +- appendix/list.md | 2 +- appendix/units.md | 2 +- fields/bundle.md | 4 ++-- fields/common.md | 24 ++++++++++++++++++++---- fields/enum.md | 10 +++++----- fields/fields.md | 2 +- fields/int.md | 2 +- fields/list.md | 4 ++-- fields/set.md | 2 +- frames/checksum.md | 2 +- frames/custom.md | 3 --- frames/frames.md | 4 ++-- frames/value.md | 2 +- intro/properties.md | 4 ++-- intro/protocol_versioning.md | 2 +- intro/references.md | 2 +- intro/version.md | 2 +- schema/schema.md | 4 ++-- 21 files changed, 48 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index ca5693c..4d12f6d 100644 --- 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 index 3e7e8d6..28da6ee 100644 --- 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 index de12614..482a7d3 100644 --- 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 index 52c83ea..9a1b80d 100644 --- 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 index 58bf9f5..2bb970d 100644 --- 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 index bce605f..89a59fd 100644 --- a/fields/bundle.md +++ b/fields/bundle.md @@ -51,9 +51,9 @@ of the **<bundle>**, then all the members must be wrapped in ``` #### Reusing Other Bundle -Like any other field **<bundle>** supports **reuse** of any other **<bundle>**. +Like any other field, **<bundle>** supports **reuse** of any other **<bundle>**. Such reuse copies all the fields from original **<bundle>** 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. ``` diff --git a/fields/common.md b/fields/common.md index 3d37680..c57f6b8 100644 --- 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: ``` @@ -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. ``` @@ -90,15 +90,31 @@ If **displayName** is not specified, the code generator must use value of proper ``` -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. +``` + + + + + + +``` -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. +``` + + + + + + +``` #### Versioning **CommsDSL** allows providing an information in what version the field was added diff --git a/fields/enum.md b/fields/enum.md index f5a7a2f..6a2f996 100644 --- 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 **<validValue>** 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 **<enum>** field. However there may be protocols, that limit serialization +of the **<enum>** 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 **<validValue>**-es use the same value of **val** +an error if two different **<validValue>**-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 index 54c74ef..afde28b 100644 --- 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 **<fields>** node of the [<schema>](../intro/schema_def.md) or [<ns>](../intro/namespaces.md) can be referenced by other fields to avoid -definition duplication. +duplication of the same definition. ``` diff --git a/fields/int.md b/fields/int.md index 131e970..14e4c5d 100644 --- 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 index 26f1de3..0a29228 100644 --- a/fields/list.md +++ b/fields/list.md @@ -242,7 +242,7 @@ length. **CommsDSL** supports such lists with **elemFixedLength** ``` -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 index 7dd1b11..186b438 100644 --- 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 **<bit>** XML child element +All the bits that aren't listed as **<bit>** 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 index 38b867f..8540506 100644 --- 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 index a4fcb60..bc699bb 100644 --- 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 - - ... - diff --git a/frames/frames.md b/frames/frames.md index 7c3e1b0..3729f7d 100644 --- a/frames/frames.md +++ b/frames/frames.md @@ -78,7 +78,7 @@ Available layers are: - [<checksum>](checksum.md) - Checksum. - [<value>](value.md) - Extra value, usually to be assigned to one of the [<interface>](../interfaces/interfaces.md) fields. -- [<custom>](custom.md) - Any other custom layer, not provided by **CommsDSL**. +- [<custom>](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 **<frame>**, then all the layers must be wrapped in @@ -96,7 +96,7 @@ of the **<frame>**, then all the layers must be wrapped in ``` -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 index 9650bb4..bb35862 100644 --- 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** **<value>** layer using **pseudo** [property](../intro/properties.md) with [boolean](../intro/boolean.md) value. The field of the pseudo **<value>** layer does not get serialized. However, the code generator must allow external diff --git a/intro/properties.md b/intro/properties.md index 37ded9e..9e24b49 100644 --- 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 index a6dff48..3d3ecb8 100644 --- a/intro/protocol_versioning.md +++ b/intro/protocol_versioning.md @@ -26,7 +26,7 @@ For example: ``` -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 index e51d3c2..6298e8b 100644 --- a/intro/references.md +++ b/intro/references.md @@ -21,7 +21,7 @@ circular references. ``` -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 index 8d99193..83bf3db 100644 --- 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 index 249c13a..03fe2ac 100644 --- 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