Add additional documentation on data type exports (#295)

Signed-off-by: Krishna Koppolu <[email protected]> Co-authored-by: Krishna Koppolu <[email protected]>
COVESA · Jun 27, 2023 · b8c3362 · b8c3362
1 parent 528868a
commit b8c3362
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 2 deletions.
diff --git a/docs/vspec2x.md b/docs/vspec2x.md
@@ -107,6 +107,8 @@ The export format is similar to the export format of VSS signals. The below tabl
 
 The YAML exporter maintains the file structure of the vspec file being exported.
 
+**NOTE:** For YAML and JSON, if a separate output file is not provided, the complex data types are exported under the key - `ComplexDataTypes`. See the snippets below for illustration.
+
 **CSV snippet**
 ```csv
 "Node","Type","DataType","Deprecated","Unit","Min","Max","Desc","Comment","Allowed","Default"
@@ -115,7 +117,7 @@ The YAML exporter maintains the file structure of the vspec file being exported.
 "<PropertyName>","property","<DataType>","<Deprecation>","<Unit>","<Min>","<Max>","<Description>","<Comment>","<Allowed values>","<Default Value>"
 ```
 
-**JSON snippet**
+**JSON snippet (data types are exported to a separate file)**
 ```json
 {
   "VehicleDataTypes": {
@@ -143,6 +145,41 @@ The YAML exporter maintains the file structure of the vspec file being exported.
 }
 ```
 
+**JSON snippet (signals and data types are exported to a single file)**
+```json
+{
+  "Vehicle": {
+    "type": "branch"
+    // Signal tree
+  },
+  "ComplexDataTypes": {
+    "VehicleDataTypes": {
+      // complex data type tree
+      "children": {
+        "<Branch>": {
+          "children": {
+            "<Struct>": {
+              "children": {
+                "<Property>": {
+                  "type": "property",
+                  "datatype": "<Data Type>",
+                  "description": "<Description",
+                  //                  ...
+                }
+              },
+              "description": "<Description>",
+              "type": "struct"
+            }
+          }
+          "description": "<Description>",
+          "type": "branch"
+        }
+      }
+    }
+  }
+}
+```
+
 ## Handling of units
 
 The tooling verifies that only pre-defined units are used, like `kPa`and `percent`.

diff --git a/vspec2x.py b/vspec2x.py
@@ -98,7 +98,10 @@ def main(arguments):
                             default=[],
                             help='Data types file in vspec format.')
     type_group.add_argument('-ot', '--types-output-file', metavar='<types_output_file>',
-                            help='Output file for writing data types from vspec file.')
+                            help='Output file for writing data types from vspec file. ' +
+                                 'If not specified, a single file is used where applicable. ' +
+                                 'In case of JSON and YAML, the data is exported under a ' +
+                                 'special key - "ComplexDataTypes"')
 
     for entry in Exporter:
         entry.value.add_arguments(parser.add_argument_group(