search

superfaceai / cli

Let AI connect the APIs for you
https://superface.ai
MIT License
22 stars 4 forks source link

[Feedback] add additional comments at the top of generated files #356

Open julpat opened 1 year ago

julpat commented 1 year ago

Feedback

When users are discovering generated files, they miss the context, purpose, and relations of these files right away. They are forced to google/go to documentation and lose the flow.

Possible solution

To help with that add brief comments at the top of each generated file. It will describe the purpose and relations with other files (where is it in the Superface), link to the glossary, and indicate usage (profile to change inputs/outputs; map to debug integration; ..).

Jakub-Vacek commented 1 year ago

This might be complicated for provider definition (JSON) but otherwise should be ok (Engine adding Comlink/JS comment on top of each generated file)