Improve README.md documentation for extensions

compiler/extensions/cpp/README.md

@@ -1,7 +1,7 @@
 # C++ Generator for Zserio
 
-Zserio extension which generates C++ [serialization API](serialization-api) from the Zserio schema
-together with [additional API](#additional-api).
+Zserio extension generates C++ [serialization API](#serialization-api) from the Zserio schema together
+with [additional API](#additional-api).
 
 The generated code must be always linked with [C++ Runtime Library](https://zserio.org/doc/runtime/latest/cpp)
 which provides functionality common for all generated code.
@@ -200,7 +200,7 @@ choices and unions:
 - Export to the JSON string
   (method [`zserio::toJsonString()`](https://zserio.org/doc/runtime/latest/cpp/DebugStringUtil_8h.html)).
 - Import from the JSON string
-  (method [`zserio::toJsonString()`](https://zserio.org/doc/runtime/latest/cpp/DebugStringUtil_8h.html)).
+  (method [`zserio::fromJsonString()`](https://zserio.org/doc/runtime/latest/cpp/DebugStringUtil_8h.html)).
 
 > Note that this feature is available only if type information and reflections are enabled!
 

compiler/extensions/doc/README.md

@@ -1,13 +1,15 @@
 # Documentation Generator for Zserio
 
-Zserio extension which generates HTML documentation from the Zserio schema.
+Zserio extension generates HTML documentation from the Zserio schema.
 
 The documentation contains all entities defined in the schema together with well formatted comments,
 provides easy navigation via cross references and implements a simple quick search. Single HTML page per each
 package is generated.
 
 It can also generate collaboration diagrams as SVG images.
 
+The main entry point of the generated HTML documentation is `index.html`.
+
 ## Documentation comments
 
 Zserio language distinguish two formats of documentation comments -

compiler/extensions/java/README.md

@@ -1,18 +1,55 @@
 # Java Generator for Zserio
 
-Zserio extension which generates Java serialization API from the Zserio schema.
+Zserio extension generates Java [serialization API](#serialization-api) from the Zserio schema together
+with [additional API](#additional-api).
+
+The generated code must be always used with [Java Runtime Library](https://zserio.org/doc/runtime/latest/java)
+which provides functionality common for all generated code.
 
 For a **quick start** see the [Java Tutorial](https://github.com/ndsev/zserio-tutorial-java#zserio-java-quick-start-tutorial).
 
-For an **API documentation** see the [Java Runtime Library](https://zserio.org/doc/runtime/latest/java).
+## Content
+
+[Supported Java Versions](#supported-java-versions)
+
+[Serialization API](#serialization-api)
+
+        [Subtypes](#subtypes)
+
+[Additional API](#additional-api)
+
+        [Range Check](#range-check)
+
+        [Validation](#validation)
+
+        [Code Comments](#code-comments)
+
+        [Type Information](#type-information)
+
+        [JSON Debug String](#json-debug-string)
+
+[Compatibility Check](#compatibility-check)
 
 ## Supported Java Versions
 
 Zserio Java generator supports the Java SE 8 (LTS), the Java SE 11 (LTS) and the Java SE 17 (LTS).
 
 Although newer Java versions are not tested, they should work as well as long as they are backward compatible.
 
-## Subtypes
+## Serialization API
+
+The serialization API provides the following features for all Zserio structures, choices and unions:
+
+- Serialization of all Zserio objects to the bit stream
+  (method [`zserio.runtime.io.SerializeUtil.serialize()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/io/SerializeUtil.html)).
+- Deserialization of all Zserio objects from the bit stream
+  (method [`zserio.runtime.io.SerializeUtil.deserialize()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/io/SerializeUtil.html)).
+- Getters and setters for all fields
+- Method `bitSizeOf()` which calculates a number of bits needed for serialization of the Zserio object.
+- Method `equals()` which compares two Zserio objects field by field.
+- Method `hashCode()` which calculates a hash code of the Zserio object.
+
+### Subtypes
 
 Because Java language does not support aliases for types, Zserio subtypes in Java are resolved during
 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
 > Note: Subtypes of primitive types are not reflected in generated code at all. This is because simple types
   are unboxed and other built-in types (e.g. String) are final (i.e. not possible to inherit).
 
+## Additional API
+
+The following additional API features which are disabled by default, are available for users:
+
+- [Range Check](#range-check) - Generation of code for the range checking for fields and parameters (integer types only).
+- [Validation](#validation) - Generation of code which is used for SQLite databases validation.
+- [Code Comments](#code-comments) - Generation of Javadoc comments in code.
+- [Type Information](#type-information) - Generation of static information about Zserio objects like schema names, types, etc.
+- [JSON Debug String](#json-debug-string) - Supports export/import of all Zserio objects to/from the JSON file.
+
+All of these features can be enabled using command line options which are described in the
+[Zserio User Guide](../../../doc/ZserioUserGuide.md#zserio-command-line-interface) document.
+
+### Range Check
+
+Because not all Zserio integer types can be directly mapped to the Java types (e.g. `bit:4` is mapped to
+`byte`), it can be helpful to explicitly check values stored in Java types for the correct ranges
+(e.g to check if `byte` value which holds `bit:4`, is from range `<0, 15>`). Such explicit checks allow
+throwing exception with the detailed description of the Zserio field with wrong value.
+
+The range check code is generated only in the setters method directly before the field is set.
+
+### Validation
+
+The validation generates method `validate()` in all generated SQL databases. This method validates all
+SQL tables which are present in the SQL database. The SQL table validation consists of the following steps:
+
+- The check of the SQL table schema making sure that SQL table has the same schema as defined in Zserio.
+- The check of all columns in all rows making sure that values stored in the SQL table columns are valid.
+
+The check of all columns consists of the following steps:
+
+- The check of the column type making sure that SQL column type is the same as defined in Zserio.
+- The check of all blobs making sure that the blob is possible to parse successfully.
+- The check of all integer types making sure that integer values are in the correct range as defined in Zserio.
+- The check of all enumeration types making sure that enumeration values are valid as defined in Zserio.
+- The check of all bitmask types making sure that bitmask values are valid as defined in Zserio.
+
+### Code Comments
+
+The code comments generate Javadoc comments for all generated Zserio objects. Some comments available
+in Zserio schema are used as well.
+
+### Type Information
+
+The type information generates static method `typeInfo()` in all generated Zserio types (except of Zserio
+subtypes). This method returns all static information of Zserio type which is available in the Zserio schema
+(e.g. schema name, if field is optional, if field is array, etc...).
+
+### JSON Debug String
+
+JSON debug string feature provides export and import to/from JSON string for all Zserio structures,
+choices and unions:
+
+- Export to the JSON string
+  (method [`zserio.runtime.DebugStringUtil.toJsonString()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/DebugStringUtil.html)).
+- Import from the JSON string
+  (method [`zserio.runtime.DebugStringUtil.fromJsonString()`](https://zserio.org/doc/runtime/latest/java/zserio/runtime/DebugStringUtil.html)).
+
+> Note that this feature is available only if type information is enabled!
+
 ## Compatibility check
 
 Java generator honors the `zserio_compatibility_version` specified in the schema. However note that only

compiler/extensions/python/README.md

@@ -1,18 +1,58 @@
 # Python Generator for Zserio
 
-Zserio extension which generates Python serialization API from the Zserio schema.
+Zserio extension generates Python [serialization API](#serialization-api) from the Zserio schema together
+with [additional API](#additional-api).
+
+The generated code must be always used with
+[Python Runtime Library](https://zserio.org/doc/runtime/latest/python) which provides functionality common for
+all generated code.
 
 For a **quick start** see the [Python Tutorial](https://github.com/ndsev/zserio-tutorial-python#zserio-python-quick-start-tutorial).
 
-For an **API documentation** see the [Python Runtime Library](https://zserio.org/doc/runtime/latest/python).
+## Content
+
+[Supported Python Versions](#supported-python-versions)
+
+[Serialization API](#serialization-api)
+
+        [Auto-generated API helper](#auto-generated-api-helper)
+
+        [PEP-8 compliant API](#pep-8-compliant-api)
+
+                [Possible clashing](#possible-clashing)
+
+[Additional API](#additional-api)
+
+        [Range Check](#range-check)
 
-## Supported Python Version
+        [Code Comments](#code-comments)
 
-Zserio Python generator supports the Python 3.8, 3.9, 3.10 and 3.11.
+        [Type Information](#type-information)
+
+        [JSON Debug String](#json-debug-string)
+
+[Compatibility Check](#compatibility-check)
+
+## Supported Python Versions
+
+Zserio Python generator supports the Python 3.8, 3.9, 3.10, 3.11 and 3.12.
 
 Although newer Python versions are not tested, they should work as well as long as they are backward compatible.
 
-## Auto-generated API helper
+## Serialization API
+
+The serialization API provides the following features for all Zserio structures, choices and unions:
+
+- Serialization of all Zserio objects to the bit stream
+  (method [`zserio.serialization.serialize()`](https://zserio.org/doc/runtime/latest/python/zserio.serialization.html#module-zserio.serialization)).
+- Deserialization of all Zserio objects from the bit stream
+  (method [`zserio.serialization.deserialize()`](https://zserio.org/doc/runtime/latest/python/zserio.serialization.html#module-zserio.serialization)).
+- Properties for all fields to get and set values
+- Method `bitsizeof()` which calculates a number of bits needed for serialization of the Zserio object.
+- Method `__eq__()` which compares two Zserio objects field by field.
+- Method `__hash__()` which calculates a hash code of the Zserio object.
+
+### Auto-generated API helper
 
 Python Generator generates each package symbol in its own Python module (i.e. file). It's necessary in order
 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()
 testUnion = my_package.other_package.TestUnion()
 ```
 
-## PEP-8 compliant API
+### PEP-8 compliant API
 
 Python generator generates the serialization API according to the
 [PEP-8](https://www.python.org/dev/peps/pep-0008/). It means that the generator must rename symbols defined
 in the Zserio schema to conform PEP-8 style guide. However such renaming can introduce symbol clashing which
 could not be detected by the Zserio core. Therefore the Python generator must do its own checks and can cause
 generation failure in case that it detects some clashing.
 
-### Possible clashing
+#### Possible clashing
 
 1. Names of generated files for package symbols (structures, choices, constants, etc.) -
    i.e. Python module names:
-    * may clash with names of generated Python packages defined in the Zserio schema which causes problems to
-      Python import system which cannot distinguish easily between module and package with the same name
-    * may clash with other modules generated for another package symbols (both `SomeStruct` and `Some_Struct`
-      are generated like `some_struct.py` module)
-    * may clash with auto-generated `api.py`
+   - may clash with names of generated Python packages defined in the Zserio schema which causes problems to
+     Python import system which cannot distinguish easily between module and package with the same name
+   - may clash with other modules generated for another package symbols (both `SomeStruct` and `Some_Struct`
+     are generated like `some_struct.py` module)
+   - may clash with auto-generated `api.py`
 
 2. Names of symbols in a scope (field names, enum item names, function names, etc.):
-    * may clash between each other (both `some_field` and `someField` are generated like `some_field` Python
-      property)
-    * may clash with some of the generated API methods - e.g. `read`, `write`, `bitsizeof`, etc.
-    * may clash with some private member or reserved symbol - for simplicity, Python generator forbids
+   - may clash between each other (both `some_field` and `someField` are generated like `some_field` Python
+     property)
+   - may clash with some of the generated API methods - e.g. `read`, `write`, `bitsizeof`, etc.
+   - may clash with some private member or reserved symbol - for simplicity, Python generator forbids
      identifiers starting with underscore (`_`)
 
 3. Top level package name
-    * top level package name should be carefully chosen since Python import system is not much robust -
-      e.g. all the packages and modules which are imported during Python startup are set in `sys.modules` and
-      it isn't possible to import another package with the same name, at least not using classic import syntax
-    * since it's not clear which packages/modules are imported during Python startup
-      (and moreover the list probably isn't fixed across Python versions), the Python Generator doesn't try
-      to detect such clashes and it's up to user to choose a safe name
-    * in case that the top level package name cannot be change, user can use `-setTopLevelPackage` Zserio option
-      which allows to set an additional top level package
-    * Python Generator only checks for possible clashes with packages/modules which the generated serialization
-      API uses, which is currently only `zserio` and `typing`
+   - top level package name should be carefully chosen since Python import system is not much robust -
+     e.g. all the packages and modules which are imported during Python startup are set in `sys.modules` and
+     it isn't possible to import another package with the same name, at least not using classic import syntax
+   - since it's not clear which packages/modules are imported during Python startup
+     (and moreover the list probably isn't fixed across Python versions), the Python Generator doesn't try
+     to detect such clashes and it's up to user to choose a safe name
+   - in case that the top level package name cannot be change, user can use `-setTopLevelPackage` Zserio option
+     which allows to set an additional top level package
+   - Python Generator only checks for possible clashes with packages/modules which the generated serialization
+     API uses, which is currently only `zserio` and `typing`
+
+## Additional API
+
+The following additional API features which are disabled by default, are available for users:
+
+- [Range Check](#range-check) - Generation of code for the range checking for fields and parameters (integer types only).
+- [Code Comments](#code-comments) - Generation of Javadoc comments in code.
+- [Type Information](#type-information) - Generation of static information about Zserio objects like schema names, types, etc.
+- [JSON Debug String](#json-debug-string) - Supports export/import of all Zserio objects to/from the JSON file.
+
+All of these features can be enabled using command line options which are described in the
+[Zserio User Guide](../../../doc/ZserioUserGuide.md#zserio-command-line-interface) document.
+
+### Range Check
+
+Because not all Zserio integer types can be directly mapped to the Python types (e.g. `bit:4` is mapped to
+`int`), it can be helpful to explicitly check values stored in Java types for the correct ranges
+(e.g to check if `int` value which holds `bit:4`, is from range `<0, 15>`). Such explicit checks allow
+throwing exception with the detailed description of the Zserio field with wrong value.
+
+The range check code is generated only in the `write()` method directly before the field is written to the
+bit stream.
+
+### Code Comments
+
+The code comments generate Sphinx comments for all generated Zserio objects. Some comments available
+in Zserio schema are used as well.
+
+### Type Information
+
+The type information generates static method `type_info()` in all generated Zserio types (except of Zserio
+subtypes). This method returns all static information of Zserio type which is available in the Zserio schema
+(e.g. schema name, if field is optional, if field is array, etc...).
+
+### JSON Debug String
+
+JSON debug string feature provides export and import to/from JSON string for all Zserio structures,
+choices and unions:
+
+- Export to the JSON string
+  (method [`zserio.debugstring.to_json_string()`](https://zserio.org/doc/runtime/latest/python/zserio.debugstring.html#module-zserio.debugstring)).
+- Import from the JSON string
+  (method [`zserio.debugstring.from_json_string()`](https://zserio.org/doc/runtime/latest/python/zserio.debugstring.html#module-zserio.debugstring)).
+
+> Note that this feature is available only if type information is enabled!
 
 ## Compatibility check
 

compiler/extensions/xml/README.md

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