Skip to content

Commit 8937a39

Browse files
mikirmikir
committed
[#597] Improve README.md documentation for extensions
1 parent 3325548 commit 8937a39

File tree

5 files changed

+221
-35
lines changed

5 files changed

+221
-35
lines changed

‎compiler/extensions/cpp/README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# C++ Generator for Zserio
22

3-
Zserio extension which generates C++ [serialization API](serialization-api) from the Zserio schema
4-
together with [additional API](#additional-api).
3+
Zserio extension generates C++ [serialization API](#serialization-api) from the Zserio schema together
4+
with [additional API](#additional-api).
55

66
The generated code must be always linked with [C++ Runtime Library](https://zserio.org/doc/runtime/latest/cpp)
77
which provides functionality common for all generated code.
@@ -200,7 +200,7 @@ choices and unions:
200200
- Export to the JSON string
201201
(method [`zserio::toJsonString()`](https://zserio.org/doc/runtime/latest/cpp/DebugStringUtil_8h.html)).
202202
- Import from the JSON string
203-
(method [`zserio::toJsonString()`](https://zserio.org/doc/runtime/latest/cpp/DebugStringUtil_8h.html)).
203+
(method [`zserio::fromJsonString()`](https://zserio.org/doc/runtime/latest/cpp/DebugStringUtil_8h.html)).
204204

205205
> Note that this feature is available only if type information and reflections are enabled!
206206

‎compiler/extensions/doc/README.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
# Documentation Generator for Zserio
22

3-
Zserio extension which generates HTML documentation from the Zserio schema.
3+
Zserio extension generates HTML documentation from the Zserio schema.
44

55
The documentation contains all entities defined in the schema together with well formatted comments,
66
provides easy navigation via cross references and implements a simple quick search. Single HTML page per each
77
package is generated.
88

99
It can also generate collaboration diagrams as SVG images.
1010

11+
The main entry point of the generated HTML documentation is `index.html`.
12+
1113
## Documentation comments
1214

1315
Zserio language distinguish two formats of documentation comments -

‎compiler/extensions/java/README.md

+101-3
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,55 @@
11
# Java Generator for Zserio
22

3-
Zserio extension which generates Java serialization API from the Zserio schema.
3+
Zserio extension generates Java [serialization API](#serialization-api) from the Zserio schema together
4+
with [additional API](#additional-api).
5+
6+
The generated code must be always used with [Java Runtime Library](https://zserio.org/doc/runtime/latest/java)
7+
which provides functionality common for all generated code.
48

59
For a **quick start** see the [Java Tutorial](https://github.com/ndsev/zserio-tutorial-java#zserio-java-quick-start-tutorial).
610

7-
For an **API documentation** see the [Java Runtime Library](https://zserio.org/doc/runtime/latest/java).
11+
## Content
12+
13+
[Supported Java Versions](#supported-java-versions)
14+
15+
[Serialization API](#serialization-api)
16+
17+
        [Subtypes](#subtypes)
18+
19+
[Additional API](#additional-api)
20+
21+
        [Range Check](#range-check)
22+
23+
        [Validation](#validation)
24+
25+
        [Code Comments](#code-comments)
26+
27+
        [Type Information](#type-information)
28+
29+
        [JSON Debug String](#json-debug-string)
30+
31+
[Compatibility Check](#compatibility-check)
832

933
## Supported Java Versions
1034

1135
Zserio Java generator supports the Java SE 8 (LTS), the Java SE 11 (LTS) and the Java SE 17 (LTS).
1236

1337
Although newer Java versions are not tested, they should work as well as long as they are backward compatible.
1438

15-
## Subtypes
39+
## Serialization API
40+
41+
The serialization API provides the following features for all Zserio structures, choices and unions:
42+
43+
- Serialization of all Zserio objects to the bit stream
44+
(method [`zserio.runtime.io.SerializeUtil.serialize()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/io/SerializeUtil.html)).
45+
- Deserialization of all Zserio objects from the bit stream
46+
(method [`zserio.runtime.io.SerializeUtil.deserialize()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/io/SerializeUtil.html)).
47+
- Getters and setters for all fields
48+
- Method `bitSizeOf()` which calculates a number of bits needed for serialization of the Zserio object.
49+
- Method `equals()` which compares two Zserio objects field by field.
50+
- Method `hashCode()` which calculates a hash code of the Zserio object.
51+
52+
### Subtypes
1653

1754
Because Java language does not support aliases for types, Zserio subtypes in Java are resolved during
1855
API generation (resolved means that generated Java API uses always original type directly).
@@ -26,6 +63,67 @@ subtype classes are not used by generated code and are just meant to support app
2663
> Note: Subtypes of primitive types are not reflected in generated code at all. This is because simple types
2764
are unboxed and other built-in types (e.g. String) are final (i.e. not possible to inherit).
2865

66+
## Additional API
67+
68+
The following additional API features which are disabled by default, are available for users:
69+
70+
- [Range Check](#range-check) - Generation of code for the range checking for fields and parameters (integer types only).
71+
- [Validation](#validation) - Generation of code which is used for SQLite databases validation.
72+
- [Code Comments](#code-comments) - Generation of Javadoc comments in code.
73+
- [Type Information](#type-information) - Generation of static information about Zserio objects like schema names, types, etc.
74+
- [JSON Debug String](#json-debug-string) - Supports export/import of all Zserio objects to/from the JSON file.
75+
76+
All of these features can be enabled using command line options which are described in the
77+
[Zserio User Guide](../../../doc/ZserioUserGuide.md#zserio-command-line-interface) document.
78+
79+
### Range Check
80+
81+
Because not all Zserio integer types can be directly mapped to the Java types (e.g. `bit:4` is mapped to
82+
`byte`), it can be helpful to explicitly check values stored in Java types for the correct ranges
83+
(e.g to check if `byte` value which holds `bit:4`, is from range `<0, 15>`). Such explicit checks allow
84+
throwing exception with the detailed description of the Zserio field with wrong value.
85+
86+
The range check code is generated only in the setters method directly before the field is set.
87+
88+
### Validation
89+
90+
The validation generates method `validate()` in all generated SQL databases. This method validates all
91+
SQL tables which are present in the SQL database. The SQL table validation consists of the following steps:
92+
93+
- The check of the SQL table schema making sure that SQL table has the same schema as defined in Zserio.
94+
- The check of all columns in all rows making sure that values stored in the SQL table columns are valid.
95+
96+
The check of all columns consists of the following steps:
97+
98+
- The check of the column type making sure that SQL column type is the same as defined in Zserio.
99+
- The check of all blobs making sure that the blob is possible to parse successfully.
100+
- The check of all integer types making sure that integer values are in the correct range as defined in Zserio.
101+
- The check of all enumeration types making sure that enumeration values are valid as defined in Zserio.
102+
- The check of all bitmask types making sure that bitmask values are valid as defined in Zserio.
103+
104+
### Code Comments
105+
106+
The code comments generate Javadoc comments for all generated Zserio objects. Some comments available
107+
in Zserio schema are used as well.
108+
109+
### Type Information
110+
111+
The type information generates static method `typeInfo()` in all generated Zserio types (except of Zserio
112+
subtypes). This method returns all static information of Zserio type which is available in the Zserio schema
113+
(e.g. schema name, if field is optional, if field is array, etc...).
114+
115+
### JSON Debug String
116+
117+
JSON debug string feature provides export and import to/from JSON string for all Zserio structures,
118+
choices and unions:
119+
120+
- Export to the JSON string
121+
(method [`zserio.runtime.DebugStringUtil.toJsonString()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/DebugStringUtil.html)).
122+
- Import from the JSON string
123+
(method [`zserio.runtime.DebugStringUtil.fromJsonString()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/DebugStringUtil.html)).
124+
125+
> Note that this feature is available only if type information is enabled!
126+
29127
## Compatibility check
30128

31129
Java generator honors the `zserio_compatibility_version` specified in the schema. However note that only

‎compiler/extensions/python/README.md

+111-26
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,58 @@
11
# Python Generator for Zserio
22

3-
Zserio extension which generates Python serialization API from the Zserio schema.
3+
Zserio extension generates Python [serialization API](#serialization-api) from the Zserio schema together
4+
with [additional API](#additional-api).
5+
6+
The generated code must be always used with
7+
[Python Runtime Library](https://zserio.org/doc/runtime/latest/python) which provides functionality common for
8+
all generated code.
49

510
For a **quick start** see the [Python Tutorial](https://github.com/ndsev/zserio-tutorial-python#zserio-python-quick-start-tutorial).
611

7-
For an **API documentation** see the [Python Runtime Library](https://zserio.org/doc/runtime/latest/python).
12+
## Content
13+
14+
[Supported Python Versions](#supported-python-versions)
15+
16+
[Serialization API](#serialization-api)
17+
18+
&nbsp; &nbsp; &nbsp; &nbsp; [Auto-generated API helper](#auto-generated-api-helper)
19+
20+
&nbsp; &nbsp; &nbsp; &nbsp; [PEP-8 compliant API](#pep-8-compliant-api)
21+
22+
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; [Possible clashing](#possible-clashing)
23+
24+
[Additional API](#additional-api)
25+
26+
&nbsp; &nbsp; &nbsp; &nbsp; [Range Check](#range-check)
827

9-
## Supported Python Version
28+
&nbsp; &nbsp; &nbsp; &nbsp; [Code Comments](#code-comments)
1029

11-
Zserio Python generator supports the Python 3.8, 3.9, 3.10 and 3.11.
30+
&nbsp; &nbsp; &nbsp; &nbsp; [Type Information](#type-information)
31+
32+
&nbsp; &nbsp; &nbsp; &nbsp; [JSON Debug String](#json-debug-string)
33+
34+
[Compatibility Check](#compatibility-check)
35+
36+
## Supported Python Versions
37+
38+
Zserio Python generator supports the Python 3.8, 3.9, 3.10, 3.11 and 3.12.
1239

1340
Although newer Python versions are not tested, they should work as well as long as they are backward compatible.
1441

15-
## Auto-generated API helper
42+
## Serialization API
43+
44+
The serialization API provides the following features for all Zserio structures, choices and unions:
45+
46+
- Serialization of all Zserio objects to the bit stream
47+
(method [`zserio.serialization.serialize()`](https://zserio.org/doc/runtime/latest/python/zserio.serialization.html#module-zserio.serialization)).
48+
- Deserialization of all Zserio objects from the bit stream
49+
(method [`zserio.serialization.deserialize()`](https://zserio.org/doc/runtime/latest/python/zserio.serialization.html#module-zserio.serialization)).
50+
- Properties for all fields to get and set values
51+
- Method `bitsizeof()` which calculates a number of bits needed for serialization of the Zserio object.
52+
- Method `__eq__()` which compares two Zserio objects field by field.
53+
- Method `__hash__()` which calculates a hash code of the Zserio object.
54+
55+
### Auto-generated API helper
1656

1757
Python Generator generates each package symbol in its own Python module (i.e. file). It's necessary in order
1858
to prevent problems with Python symbols dependencies. Zserio allows dependencies which are defined after the
@@ -40,42 +80,87 @@ testStructure = my_package.sub_package.TestStructure()
4080
testUnion = my_package.other_package.TestUnion()
4181
```
4282

43-
## PEP-8 compliant API
83+
### PEP-8 compliant API
4484

4585
Python generator generates the serialization API according to the
4686
[PEP-8](https://www.python.org/dev/peps/pep-0008/). It means that the generator must rename symbols defined
4787
in the Zserio schema to conform PEP-8 style guide. However such renaming can introduce symbol clashing which
4888
could not be detected by the Zserio core. Therefore the Python generator must do its own checks and can cause
4989
generation failure in case that it detects some clashing.
5090

51-
### Possible clashing
91+
#### Possible clashing
5292

5393
1. Names of generated files for package symbols (structures, choices, constants, etc.) -
5494
i.e. Python module names:
55-
* may clash with names of generated Python packages defined in the Zserio schema which causes problems to
56-
Python import system which cannot distinguish easily between module and package with the same name
57-
* may clash with other modules generated for another package symbols (both `SomeStruct` and `Some_Struct`
58-
are generated like `some_struct.py` module)
59-
* may clash with auto-generated `api.py`
95+
- may clash with names of generated Python packages defined in the Zserio schema which causes problems to
96+
Python import system which cannot distinguish easily between module and package with the same name
97+
- may clash with other modules generated for another package symbols (both `SomeStruct` and `Some_Struct`
98+
are generated like `some_struct.py` module)
99+
- may clash with auto-generated `api.py`
60100

61101
2. Names of symbols in a scope (field names, enum item names, function names, etc.):
62-
* may clash between each other (both `some_field` and `someField` are generated like `some_field` Python
63-
property)
64-
* may clash with some of the generated API methods - e.g. `read`, `write`, `bitsizeof`, etc.
65-
* may clash with some private member or reserved symbol - for simplicity, Python generator forbids
102+
- may clash between each other (both `some_field` and `someField` are generated like `some_field` Python
103+
property)
104+
- may clash with some of the generated API methods - e.g. `read`, `write`, `bitsizeof`, etc.
105+
- may clash with some private member or reserved symbol - for simplicity, Python generator forbids
66106
identifiers starting with underscore (`_`)
67107

68108
3. Top level package name
69-
* top level package name should be carefully chosen since Python import system is not much robust -
70-
e.g. all the packages and modules which are imported during Python startup are set in `sys.modules` and
71-
it isn't possible to import another package with the same name, at least not using classic import syntax
72-
* since it's not clear which packages/modules are imported during Python startup
73-
(and moreover the list probably isn't fixed across Python versions), the Python Generator doesn't try
74-
to detect such clashes and it's up to user to choose a safe name
75-
* in case that the top level package name cannot be change, user can use `-setTopLevelPackage` Zserio option
76-
which allows to set an additional top level package
77-
* Python Generator only checks for possible clashes with packages/modules which the generated serialization
78-
API uses, which is currently only `zserio` and `typing`
109+
- top level package name should be carefully chosen since Python import system is not much robust -
110+
e.g. all the packages and modules which are imported during Python startup are set in `sys.modules` and
111+
it isn't possible to import another package with the same name, at least not using classic import syntax
112+
- since it's not clear which packages/modules are imported during Python startup
113+
(and moreover the list probably isn't fixed across Python versions), the Python Generator doesn't try
114+
to detect such clashes and it's up to user to choose a safe name
115+
- in case that the top level package name cannot be change, user can use `-setTopLevelPackage` Zserio option
116+
which allows to set an additional top level package
117+
- Python Generator only checks for possible clashes with packages/modules which the generated serialization
118+
API uses, which is currently only `zserio` and `typing`
119+
120+
## Additional API
121+
122+
The following additional API features which are disabled by default, are available for users:
123+
124+
- [Range Check](#range-check) - Generation of code for the range checking for fields and parameters (integer types only).
125+
- [Code Comments](#code-comments) - Generation of Javadoc comments in code.
126+
- [Type Information](#type-information) - Generation of static information about Zserio objects like schema names, types, etc.
127+
- [JSON Debug String](#json-debug-string) - Supports export/import of all Zserio objects to/from the JSON file.
128+
129+
All of these features can be enabled using command line options which are described in the
130+
[Zserio User Guide](../../../doc/ZserioUserGuide.md#zserio-command-line-interface) document.
131+
132+
### Range Check
133+
134+
Because not all Zserio integer types can be directly mapped to the Python types (e.g. `bit:4` is mapped to
135+
`int`), it can be helpful to explicitly check values stored in Java types for the correct ranges
136+
(e.g to check if `int` value which holds `bit:4`, is from range `<0, 15>`). Such explicit checks allow
137+
throwing exception with the detailed description of the Zserio field with wrong value.
138+
139+
The range check code is generated only in the `write()` method directly before the field is written to the
140+
bit stream.
141+
142+
### Code Comments
143+
144+
The code comments generate Sphinx comments for all generated Zserio objects. Some comments available
145+
in Zserio schema are used as well.
146+
147+
### Type Information
148+
149+
The type information generates static method `type_info()` in all generated Zserio types (except of Zserio
150+
subtypes). This method returns all static information of Zserio type which is available in the Zserio schema
151+
(e.g. schema name, if field is optional, if field is array, etc...).
152+
153+
### JSON Debug String
154+
155+
JSON debug string feature provides export and import to/from JSON string for all Zserio structures,
156+
choices and unions:
157+
158+
- Export to the JSON string
159+
(method [`zserio.debugstring.to_json_string()`](https://zserio.org/doc/runtime/latest/python/zserio.debugstring.html#module-zserio.debugstring)).
160+
- Import from the JSON string
161+
(method [`zserio.debugstring.from_json_string()`](https://zserio.org/doc/runtime/latest/python/zserio.debugstring.html#module-zserio.debugstring)).
162+
163+
> Note that this feature is available only if type information is enabled!
79164
80165
## Compatibility check
81166

‎compiler/extensions/xml/README.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# XML Generator for Zserio
22

3-
Zserio extension which generates XML tree from the Zserio schema. The generated XML represents the Zserio
4-
AST and is used mainly for debugging purposes.
3+
Zserio extension generates XML tree from the Zserio schema.
4+
5+
The generated XML represents the Zserio AST and it is used mainly for debugging purposes.

0 commit comments

Comments
 (0)