[Enhancement] Create codegen featureset/delta documentation table

[timothytavarez]

It would make adoption more manageable for codegen if we can clearly articulate differences in compiled results. At a minimum, we should develop a documentation summary with featuresets (e.g., inheritance, metamodel differences, etc.) that can be easily grasped at a high level.

Today, language deltas are documented separately for each codegen subtarget. By putting it in a single view, we can more readily understand differences, expected results, etc.

[timothytavarez]

I'll be happy to support adding/updating this documentation.

[dselman]

That would be great, thanks!

[Mamatha1718]

Hi @dselman, @timothytavarez
I am eager to tackle this issue. I would like to add these changes:
1.Unified Featureset Documentation:
I will create consolidated table summarizing key features and differences across all
=>Inheritance models (e.g., single, multiple, multilevel).
=>Metamodel differences (e.g., UML compliance or custom models).
=>Platform-specific constraints or optimizations.
2. Comparison of Compiled Results:
I will document examples of compiled results for each subtarget with side-by-side
comparisons to highlight key differences.
3. Language-Specific Notes:
I will add include unique features, limitations specific to each subtarget, along with code snippets for better clarity.
4. Troubleshooting and FAQ's :
addressing some common potential issues users may face. while working on
different subtargets.
5. Guidelines for Future Contributors:
Include a template or checklists for future contributors to maintain and update
the documentation effectively.
could you please clarify where i will start to work on this issue. and will you please let me know if there are another changes required.

[sanketshevkar]

Thanks @Mamatha1718 this sounds awesome!
You might want to add these details to the tech-docs repo and link it in the readme for concerto-codegen.

[Mamatha1718]

Hi @sanketshevkar ,

Thank you for your response and for assigning me this issue. Should I add these changes to an existing file? I’m a little confused about which specific file needs these changes. Could you please clarify?

Thanks for your help!

[sanketshevkar]

We have a dedicated section in our docs for codegen.
https://concerto.accordproject.org/docs/category/code-generation
I think we can reuse this space. If you are planning to add examples and info for every target language, feel free to add info in the pages deidcated to each target.

If your plan is to just add generic info then you can use the main codegen page. Depending on the content we can move around it within the codegen section itself.

[Mamatha1718]

Hi @sanketshevkar ,

Sorry for the inconvenience, but I couldn’t find the ``docs/category/code-generation/ ` location you mentioned. I searched the repository and found references to code generation in the following files:

docs/ref-cicero-cli.md
docs/ref-concerto-cli.md
website/versioned_docs/version-0.12/ref-logic-specification.md
Could you clarify where exactly I should add the updates? Is the code-generation section stored elsewhere, or should I modify one of these files?

Thanks for your help!

[sanketshevkar]

@Mamatha1718 this page should be in the concerto-docs repo. https://github.com/accordproject/concerto-docs

[Mamatha1718]

Hi @sanketshevkar , Thank you for your clarification, i am working on improving docs page,
Thank You!

[Mamatha1718]

Hi @sanketshevkar , The pull request accordproject/concerto-docs#73 is ready for review, will you please review it , can you please tell me if any other changes required.
Thank you

[github-actions]

This issue is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed.