ICD generation - Githubissues

mathisloge commented 3 years ago

Hi Alex,

I'm currently exploring the possibility to generate latex files for automatic ICD generation. there shouldn't be much missing for a ICD generation. (just the protocol aspect of a ICD.) But I think that this will be a very useful functionality.

https://github.com/mathisloge/commsdsl

I'm letting you know how it works out. Currently i need to dig a bit around the code to get a better understanding. (Don't expect me to be that fast. I'm currently writing my master thesis and working beside that)

Just by the way, really good code. I was able to find my way around quickly and generated the first latex document.

mathisloge commented 3 years ago

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

arobenko commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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.

mathisloge commented 3 years ago

Hi Alex, quick question: The StringField has a encoding state which will default to the common::encoding. (https://github.com/commschamp/commsdsl/blob/ba636a97316210beabcb8e27e15a10fa198d10d9/lib/src/StringFieldImpl.cpp#L219 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)?

arobenko commented 3 years ago

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 commented 3 years ago

Hi Alex, thanks for the explanation!

Then I will ignore the field for now.

commschamp / commsdsl

ICD generation #12