Allow emitting YAML comments (`YAMLGenerator.writeComment()`)

[lovasko]

Is it please possible to emit comment lines with the keys? I could imagine this being done with an annotation for the respective class member. Also, adding whitespace, e.g. empty line would be a nice feature as well.

If this is not currently possible, could anyone please point me to the code where this magic would be happening so that I can add this feature?

Many thanks! :)

[cowtowncoder]

There is no way to emit comments, in general, by Jackson, so it would be necessary to first figure out why this is something to add (use case, and where contents of comments should come from).
After that it would be necessary to figure out how piping of comment contents should occur (what should added, based on metadata).

So... what is the use case? Why comments? Containing what?

[IhToN]

Using a YAML file as a user-setup file in which an user will be able to change some settings in an easy way, using a notepad.

If you want to clarify some of the options you use comments so the user will be able to understand what he should modify and what will cause any of the modifications.

[cowtowncoder]

I guess I am more used to people adding comments manually, and more trying to understand how a machine-processable generation would add comments. I am familiar with comment usage in XML, where generators may add sort of prefix comment containing diagnostics metadata (generation timestamp, system etc).

I think it would be possible to add something like writeComment in base class (JsonParser) and let formats implement it if available, or throw exception if not.
Although there's further question of style of comments to use for formats that allow multiple styles (json does not have official comments, but there are 3 distinct styles that are sometimes used).

[asomov]

Even if Jackon finds a way to create API to emit comments, SnakeYAML explicitly does not support dumping comments. It is not supported by the YAML spec.

[cowtowncoder]

@asomov Hmmh. Ok, that would indeed be a blocker. I understand that retaining comments can be tricky (as they really do not play well with object models in general), wrt reading. But was assuming that there might be a way to generate them -- this was useful with XML, for example, adding comments as human-debuggable headers for things like "file generated by [tool name] on [date]" and such, instead of (or in addition to) actual machine-readable (meta)data.

[asomov]

@cowtowncoder : XML has comments as part of the spec. YAML explicitly ignores the comments.

[cowtowncoder]

@asomov I understand that. I just find this... unexpected. Thank you for pointing out point in specification.

Just one point however: while this clarifies that comments are essentially not to be exposed when reading YAML (or preserved within model), they clearly exist in textual representation. As such it would seem odd that generators could not produce them. Presumably that would mean that only humans with with text editors were to use them as... annotations?

Put another way: specification does not seem to have much to say on output/generation side, which is what this issue is about.

[asomov]

The spec says that the generation must be controlled by the composed Node tree. The comments are not part of the Node tree.
You can see that as the white space. It is present and important but it is difficult to control while dumping the output.
Of course, if a parser (jackson) could find a way to dump the comments it will be NOT against the spec.

[cowtowncoder]

@asomov Ok. I am not familiar enough with the specification there -- it is rather big spec, after all.
Thank you for pointers so far.

Another way to view this would also be whether any other YAML tools allow emission or not.
I tend to prefer working similarly to existing tools, and if (for example) such generation is not supported elsewhere, would not want to be introducing such non-compliant behavior.

At this point it does sound like adding such output may not be a good idea.

[asomov]

I do not know any tool which can generate comments.

[GotoFinal]

@asomov @cowtowncoder Are you sure that comments can't be included?
http://yaml.org/spec/1.1/#id863676
There seems to be part of representation tree, even more, you can include whole styling here. For sure you can't read this, but you can include this. Note that you can include that outside the node, just pass additional argument to emitter with data about comments/style, in my projects I had special object to store comments mapped by path.

[asomov]

Where do you see that they are a part of the tree?
This is what the spec says:

Comments are a presentation detail and must not have any effect on the serialization tree or representation graph. In particular, comments are not associated with a particular node.

" just pass additional argument to emitter with data about comments/style" - well, if you have a proposal how to implement that then feel free to share it with us.

[GotoFinal]

@asomov you ofc need own emitter then, as SnakeYaml does not support anything like that, so it is probably too complicated to include and support inside jackson

[asomov]

1. this is the issue tracker for jackson
2. SnakeYAML is not written in stone, it can be changed if we know how.
3. You said there is already a project which emits comments. Why not to share with us the API ?