Load-bearing comments

[passcod]

This is perhaps more aimed at implementations than the spec, but I think it would be really beneficial to have first-class support for comments in the APIs rather than them being silently discarded.

The main use would be when generating kdl strings from a program:

• to be able to preserve or insert comments when transforming a document
• to be able to include comments when making a new one (e.g. writing a default configuration to disk on first run)
• autoformatter, to an extent: round-trip kdl through a parser and generator and get the "canonical" form out (if that's specified at some point)

This raises questions:

1. slash dash comments are straightforward, as you already need to parse their contents to know where they stop. Output could be a node/attribute/value struct or object with the property commented=true, or something like that. However, representing the other comment types may need a separate object? It doesn't make sense to have a slash slash comment API object have children and attributes and values, surely.
2. How to represent nested comments?
3. Should non slash dash comments be parsed with an indicator of their format (slash slash or slash star)?

Regarding comments in general, there's currently no concept of attaching comments to nodes, comments are just free. E.g. semantically or structurally, should there be a difference between these two below:

general {
    colour always
}

// todo: figure out keybindings

plugins discovery=true auto-enable=false {
    inotify enable=true

    // linux: more accurate but requires permissions
    fanotify enable=on-demand
}

[hclarke]

for tools (formatters, templating, etc.), you're going to need more than just comments in order to do a round trip:

• strings can be raw (with number of #), or normal with escape sequences
• identifiers can be bare or strings (with same string things above)
• numbers can be binary/octal/hex, have underscores, leading +/-, etc.
• whitespace also comes in many shapes/sizes
• separators can be newlines or semicolons

And, the common case would be programs using KDL as a config file and such, which don't need to know about comments (and maybe shouldn't, to discourage putting data in comments?)

but also all of this is kinda necessary for tooling. i'm not sure if that means a second parser, or feature flags, or a function to convert to the simpler format. probably depends on the implementation language?

[passcod]

All very good points!

Another related question then is whether the spec should define some kind of standard for formatting a kdl document...

[hkolbeck-streem]

IMO an exact roundtrip is almost never required, because the use case is almost always creation of some canonical form. At least for quotes it seems like the canonical version would be the least-quoted one, which is what I did in the Java parser.

[zkat]

This is definitely an implementation concern, imo. For example, a serde-based parser might not want to deal with comments at all, since it only cares about data coming in, and would have some default way of dealing with data going out.

What you're talking about is what I've heard called a "document-oriented parser", which would retain comment, spacing, and input format.

I don't know if there's anything to do to allow this at the specification level, although I already made some decisions that require this type of parser for proper round-tripping for sure. But unless you're something as simple as JSON, this will usually be the case.