Preserve newlines within comments

[JorikSchellekens]

Would it be possible to maintain newlines within comments? This would allow the structure of a lot of documentation to be adhered to more closely.

[eemeli]

That should work if the newline is itself commented, but not systematically otherwise.

Conceptually, yaml attaches newlines and comments to a specific AST node, mostly as commentBefore and spaceBefore properties.

Changing this API would be rather difficult to do without breaking things, and I suspect it would also make it quite a bit more complicated to use. At the CST level, the library does parse any combination of comments and blank lines without issue, but that's much harder to use.

One possibility would be to change what happens when the parser encounters a comment-blankline-comment sequence within a document. At the moment, the blank line is dropped, but it could be replaced by a #\n line within the comment. At the very start and end of the document, those blank lines will attach the comment to the document, which in turn do get rendered with blank lines as separators. Here's an example of what I mean:

const src = `
# foo

# bar

# baz
xx
`
const doc = YAML.parseDocument(src)
String(doc)

Currently, this produces:

# foo

# bar
# baz
xx

The proposal would be to produce instead:

# foo

# bar
#
# baz
xx

To be honest, I'm not really sure which is better or less worse. Thoughts?

[JorikSchellekens]

Aside: Could we do something a little unclean by replacing the line with some place holder (say perhaps _\n), including it in the comment and transforming it back when the yaml is recreated? I don't really like exposing the _
to the user though.

Of those two options the later option is less worse I think. It's not great since it still projects the notion that

# bar
#
# baz

are somehow two semantically related comments. However the spacing still preserves some sense of grouping. For example the case that got me interested in this is:

# foo

# bar

## Header for some section

# explanation for section

# comment for particular node
xx

Which under the current scheme becomes

# foo

# bar
## Header for some section
# explanation for section
# comment for particular node

The grouped chunk becomes illegible in longer cases.

The alternative is slightly better:

# foo

# bar
#
## Header for some section
#
# explanation for section
#
# comment for particular node
xx

This is a niche case but I can't see a situation under which omitting the newline is ever better.

[JorikSchellekens]

Just realised the formatting was wrong in my previous comment.

[eemeli]

Commenting just to note that I've not forgotten about this, but probably won't get around to fixing this (and releasing a new version) for another week or so. PRs are of course welcome for the suggested alternative.