search

javanile / yamlinc

Compose multiple YAML files into one with $include tag. Split Swagger/OpenAPI into multiple YAML files.
MIT License
114 stars 22 forks source link

comments are stripped from output file #27

Open jason-henriksen opened 4 years ago

jason-henriksen commented 4 years ago

It would be much nicer if the comments in the included files were also able to appear in the output file.

Our output cloudformation file is both functional and documentation. But now people have to go dig up the sub-files in order to read the comments.

justinnichols commented 4 years ago

Two things about this:

  1. Comments are designed to be in source files, not compiled files. Since yamlinc produces a compiled file (that just happens to be readable in YAML format), it makes sense to keep the comments in the source files. However, I can see the use case of allowing them to be merged with the YAML.
  2. js-yaml is the underlying library in use in this project which reads in the YAML into a JSON object structure, merges, then writes back out in a YAML structure. js-yaml, by nature of converting to in-memory JSON objects, cannot carry over comments. Therefore, this may require a different methodology of merging files to support this enhancement. In other words, it may be outside of the scope of this project.

I am not the maintainer of this codebase, just a contributor, so I will defer to @francescobianco on whether or not yamlinc should support this, or even can support this. In the meantime, I can at least look to see what options might be available. Also, if anything I have said above is incorrect (since I haven't looked at this project in some time), please feel free to correct my mistake.

jason-henriksen commented 4 years ago

There are newer parsers that allow the comments to be maintained. It may be that the code would need a new parser or a new configuration in the existing parser.

Lacking the comments in the output file, especially for a template.yaml that's used in cloudformation is frustrating for people who just need to read the output. If nothing else, it removes the ability to put separators between sections.

justinnichols commented 4 years ago

Agreed, I definitely understand the use case. It looks like are a couple libraries that can possibly help with this: