Skip to content

Commit c640f46

Browse files
arobenkoarobenko
committed
Release v7.1
2 parents 5575b05 + ffaa3a7 commit c640f46

11 files changed

Lines changed: 187 additions & 3 deletions

File tree

‎appendix/appendix.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ include::variant.adoc[]
2323
include::units.adoc[]
2424
include::message.adoc[]
2525
include::interface.adoc[]
26+
include::namespace.adoc[]
2627
include::alias.adoc[]
2728
include::frame.adoc[]
2829
include::layers.adoc[]

‎appendix/frame.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ for detailed description.
99
|Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description
1010

1111
|**description**|string|1|no||Human readable description of the frame.
12+
|**displayName**|string|7|no||Human readable name of the frame. May be used in the documentation.
1213
|**name**|<<intro-names, name>> string|1|yes||Name of the frame.
1314
|===
1415

‎appendix/layers.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Refer to <<frames-common, Common Properties of Layers>> chapter for detailed des
88
|Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description
99

1010
|**description**|string|1|no||Human readable description of the layer.
11+
|**displayName**|string|7|no||Human readable name of the layer. May be used in the documentation.
1112
|**field**|<<fields-fields, field>> or <<intro-references, reference>> to it|1|yes (except for <<frames-payload, &lt;payload&gt; >>)||Wrapped field definition.
1213
|**name**|<<intro-names, name>> string|1|yes||Name of the layer.
1314
|===

‎appendix/namespace.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<<<
2+
[[appendix-namespace]]
3+
=== Properties of &lt;namespace&gt; ===
4+
Refer to <<namespaces-namespaces, Namespaces>> chapter
5+
for detailed description.
6+
7+
[cols="^.^28,^.^10,^.^8,^.^8,^.^10,36", options="header"]
8+
|===
9+
|Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description
10+
11+
|**description**|string|1|no||Human readable description of the namespace.
12+
|**displayName**|string|7|no||Human readable name of the namespace. May be used in the documentation.
13+
|**name**|<<intro-names, name>> string|1|yes||Name of the namespace.
14+
|===
15+

‎appendix/schema.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Refer to <<schema-schema, Schema>> chapter for detailed description.
88
|Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description
99

1010
|**description**|string|1|no||Human readable description of the protocol.
11+
|**displayName**|string|7|no||Human readable name of the schema. May be used in the documentation.
1112
|**dslVersion**|<<intro-numeric, unsigned>>|1|no|0|Version of the used DSL.
1213
|**endian**|"big" or "little"|1|no|little|Endian of the protocol.
1314
|**name**|string|1|yes||Name of the protocol. Allowed to have spaces.

‎commsdsl_spec.adoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
= CommsDSL Specification v7.0
1+
= CommsDSL Specification v7.1
22
Alex Robenko
3-
v7.0, 2025-01
3+
v7.1, 2025-08
44
:doctype: article
55
:toc: left
66
:source-highlighter: rouge
@@ -15,6 +15,7 @@ include::schema/schema.adoc[]
1515
include::fields/fields.adoc[]
1616
include::messages/messages.adoc[]
1717
include::interfaces/interfaces.adoc[]
18+
include::namespaces/namespaces.adoc[]
1819
include::aliases/aliases.adoc[]
1920
include::frames/frames.adoc[]
2021
include::versioning/versioning.adoc[]

‎frames/common.adoc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Every layer is different, and defines its own properties and/or other aspects.
44
However, there are common properties, that are applicable to every layer.
55
They are summarized below.
66

7+
[[frames-layer-name]]
78
==== Name ====
89
Every layer must define it's <<intro-names, name>>, which is expected to be
910
used by a code generator when defining a relevant class. The name is defined
@@ -19,6 +20,7 @@ using **name** <<intro-properties, property>>.
1920
</schema>
2021
----
2122

23+
[[frames-layer-description]]
2224
==== Description ====
2325
It is possible to provide a description of the layer about what it is and
2426
how it is expected to be used. This description is only for documentation
@@ -41,6 +43,24 @@ generated class. The <<intro-properties, property>> is **description**.
4143
</schema>
4244
----
4345

46+
[[frames-layer-display-name]]
47+
==== Display Name ====
48+
When documenting a layer the value of **displayName** property can be used as more descriptive
49+
human readable name.
50+
[source,xml]
51+
----
52+
<?xml version="1.0" encoding="UTF-8"?>
53+
<schema >
54+
<frame name="ProtocolFrame">
55+
<id name="Id" displayName="Message ID">
56+
...
57+
</id>
58+
<payload name="Data" />
59+
</frame>
60+
</schema>
61+
----
62+
In case **displayName** is empty, the **name** <<intro-properties, property>> is expected be used instead.
63+
4464
==== Inner Field ====
4565
Every layer, except for <<frames-payload, &lt;payload&gt; >>, needs to specify
4666
its inner <<fields-fields, field>> it wraps. The field can be specified

‎frames/frames.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ of such transport wraping using **&lt;frame&gt;** XML node.
1616
</schema>
1717
----
1818

19+
[[frames-name]]
1920
=== Name ===
2021
Every frame definition must specify its <<intro-names, name>> using
2122
**name** <<intro-properties, property>>.
@@ -29,6 +30,7 @@ Every frame definition must specify its <<intro-names, name>> using
2930
</schema>
3031
----
3132

33+
[[frames-description]]
3234
=== Description ===
3335
It is possible to provide a description of the frame about what it is and
3436
how it is expected to be used. This description is only for documentation
@@ -49,6 +51,22 @@ generated class. The <<intro-properties, property>> is **description**.
4951
</schema>
5052
----
5153

54+
[[frames-display-name]]
55+
=== Display Name ===
56+
When documenting a frame the value of **displayName** property can be used as more descriptive
57+
human readable name.
58+
[source,xml]
59+
----
60+
<?xml version="1.0" encoding="UTF-8"?>
61+
<schema >
62+
<frame name="Frame" displayName="Protocol Frame">
63+
...
64+
</frame>
65+
</schema>
66+
----
67+
In case **displayName** is empty, the **name** <<intro-properties, property>> is expected be used instead.
68+
69+
[[frames-layers]]
5270
=== Layers ===
5371
The protocol framing is defined using so called "layers", which are additional
5472
abstraction on top of <<fields-fields, fields>>, where every such layer

‎intro/namespaces.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ a separate namespace. The code generator must use this information to define
88
relevant classes in a separate namespace(s) (if such feature is provided by the
99
language) or introduce relevant prefixes into the names to avoid name clashes.
1010

11-
The namespace is defined using **&lt;ns&gt;** node with single **name** property.
11+
The namespace is defined using **&lt;ns&gt;** node with a required **name** property.
1212
It can contain all the mentioned <<schema-schema, previously>> nodes.
1313
[source,xml]
1414
----

‎namespaces/namespaces.adoc‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
2+
<<<
3+
[[namespaces-namespaces]]
4+
== Namespaces ==
5+
The namespaces can be used to help divide a specific protocol into sub-elements as
6+
well as define multiple sub-protocols in the same schema.
7+
8+
For example, having different messages with the same names defined in different namespaces.
9+
[source,xml]
10+
----
11+
<?xml version="1.0" encoding="UTF-8"?>
12+
<schema ...>
13+
<ns name="sub1">
14+
<message name="Msg1">
15+
...
16+
</message>
17+
<message name="Msg2" ... />
18+
</ns>
19+
20+
<ns name="sub2">
21+
<message name="Msg1">
22+
...
23+
</message>
24+
<message name="Msg2" ... />
25+
</ns>
26+
27+
<!-- Common Frame -->
28+
<frame name="Frame">
29+
...
30+
</frame>
31+
</schema>
32+
----
33+
34+
Another example is having multiple sub-protocols with their own frames:
35+
[source,xml]
36+
----
37+
<?xml version="1.0" encoding="UTF-8"?>
38+
<schema ...>
39+
<ns name="prot1">
40+
<message name="Msg1">
41+
...
42+
</message>
43+
<message name="Msg2" ... />
44+
45+
<frame name="Frame1">
46+
...
47+
</frame>
48+
</ns>
49+
50+
<ns name="prot2">
51+
<message name="Msg1">
52+
...
53+
</message>
54+
<message name="Msg2" ... />
55+
56+
<frame name="Frame2">
57+
...
58+
</frame>
59+
</ns>
60+
</schema>
61+
----
62+
63+
[[namespaces-name]]
64+
=== Namespace Name ===
65+
Every namespace definition must specify its <<intro-names, name>> using
66+
**name** <<intro-properties, property>>.
67+
[source,xml]
68+
----
69+
<?xml version="1.0" encoding="UTF-8"?>
70+
<schema ...>
71+
<ns name="ns1">
72+
...
73+
</ns>
74+
</schema>
75+
----
76+
77+
[[namespaces-description]]
78+
=== Description ===
79+
It is possible to provide a description of the namespace about what it is and
80+
what it contains to be used. This description is only for documentation
81+
purposes and may find it's way into the generated code as a comment for the
82+
generated namespace. The <<intro-properties, property>> is **description**.
83+
[source,xml]
84+
----
85+
<?xml version="1.0" encoding="UTF-8"?>
86+
<schema ...>
87+
<ns name="ns1">
88+
<description>
89+
Some long
90+
multiline
91+
description
92+
</description>
93+
...
94+
</ns>
95+
</schema>
96+
----
97+
98+
[[namespaces-display-name]]
99+
=== Display Name ===
100+
When documenting a namespace the value of **displayName** property can be used as more descriptive
101+
human readable name.
102+
[source,xml]
103+
----
104+
<?xml version="1.0" encoding="UTF-8"?>
105+
<schema >
106+
<ns name="ns1" displayName="Some Summary">
107+
...
108+
</ns>
109+
</schema>
110+
----
111+
In case **displayName** is empty, the **name** <<intro-properties, property>> is expected be used instead.
112+
113+
Use <<appendix-namespace, properties table>> for future references.

0 commit comments

Comments
 (0)