ICD generation

[commschamp]

ICD generation

[arobenko]

Hi Mathis,
I don't exactly understand what you mean by ICD, but I have had a long term plan to implement automatic protocol specification generated out of schema files. Unfortunately I didn't come around to actually design and implement such tool. You're more than welcome to do it yourself. However, there are a few things I want you to consider.

• Please don't try to integrate the new functionality to the existing commsdsl2comms application, even though it contains a convenient functionality of using template strings and substituting parts of it. The documentation generation functionality is really an iceberg, the hidden part of which is very easy to underestimate. For example, you'll probably eventually need an extra documentation snippets injection functionality, similar to what I did with the code.
• I'd prefer you implement it as a separate tool, that's why I split the existing functionality to libcommsdsl library (which allows easy navigation through the parsed schema files) and the code generation app like commsdsl2comms which uses the library.
• The library interface to the parsed schema files can be found here. Sorry, I didn't come around to actually documenting the interface, but it should be self explanatory in many ways. You can use parseSchemaFiles function for reference of how and where to start.
• I also suggest that at first you implement it as completely separate project, no need to fork the commsdsl repository. You can attach the commsdsl as git submodule or use it as externa project in your cmake file. Another option is to build it externally and use find_package(LibCommsdsl) in yours.
• Once you have the "production ready" version of your code you are proud of, we can consider an option to put it next to the commsdsl2comms application of this project in order to make it easily accessible to other people.
• If you really want to have the existing template portions replacement code to your disposal, we can consider moving it to the commsdsl library and make it common for all applications. As the short term solution just copy-paste it to your application. It can be cleaned later.

Hope it helps.

[mathisloge]

https://github.com/mathisloge/protocol-doc-generation

So I've worked a bit on it. But it is far away from testable. Just wanted to let you know, that there is some progress. Using https://github.com/pantor/inja to generate text from templates. In the end all structures has to be converted to an internal json structure. But, which i do like quite a lot, it is possibile to override text etc. by appying a json merge.

[arobenko]

Hi Mathis,
When I introduced the relevant code, the intention was to put the string encoding information (like ascii, utf-8, etc...) into the schema. The libcommsdsl parses and exposes its information in the API. However, the COMMS library and comms_champion project doesn't have any use for this information, and consequently commsdsl2comms code generator. At least for now. As the result I also decided not to document it in the spec and leave it as undocumented feature for the future. Besides, I still haven't decided for the range of valid values. Potentially it should become an enum instead of the string in the StringField API.

Please disregard it for now unless you really need to specify it as part of the schema, not just comment.

[mathisloge]

It might be also an option to specify eg. --icd latex or --icd asciidoc etc. to get a different output format. (or --icd custom which should be a path to a file which contains a template.)

All outputs will be templates where defined keywords will be replaced with the protocol definitions

[mathisloge]

Hi Alex,
thanks for the feedback.
An ICD generally describes way more than just the protocol, also the electrical and mechanical aspects of an interface. But this auto generation will focus only on the protocol description.
Because the description is often part of a bigger document, it should only generate the files. The user should include these into the actual document.

I'll implement it first as a standalone tool.

[mathisloge]

Hi Alex,
quick question:
The StringField has a encoding state which will default to the common::encoding. (

commsdsl/lib/src/StringFieldImpl.cpp

Line 219 in ba636a9

if (!validateSinglePropInstance(common::encodingStr())) {

and FF)
But I couldn't find any info about it in https://commschamp.github.io/commsdsl_spec/#appendix-string

Do I have to take the encoding into account or can I ignore it (treat it just a internal code gen thing)?

[mathisloge]

Hi Alex,
thanks for the explanation!

Then I will ignore the field for now.