Toml: Specify comment preservation behavior in the TOML spec

[bradleypeabody]

An issue that comes up more frequently than I believe is realized is the ability (lack thereof) to preserve comments during edits from automated tools, examples: https://github.com/toml-lang/toml/issues/284 https://github.com/JuliaLang/TOML.jl/issues/32 . Other configuration languages lack this (YAML, JSON, and to some extent XML), and adding a behavior for this to the specification would give TOML yet another leg up.

The Go programming language is a great example of where I believe they got this right. Its tools can read a source file, make edits, and spit it back out with comments preserved (except where automated modifications removed the corresponding section). I realize it's not a configuration file format, but the use case is pretty much the same - you start by hand editing it, and then later you find that since what you're doing is successful and fantastic you want to make an automated tool to handle various things, and you don't want your comments automatically evaporated when you do this.

Not every single possible comment scenario needs to be preserved exactly. E.g. if an automated tool converts a = 1 # just for now to:

# just for now
a = 1

I think such behaviors are perfectly acceptable and a workable tradeoff for being able to allow automated tools to safely modify TOML files without comment loss.

One of the challenges to different implementations adding this functionality is that there is no definition of how it should be done. I think a simple set of rules could be arrived at, which implementations could refer to and follow if they want to support this feature.

I'm sure a proposal could be worked out with an exact set of such rules if there is agreement/interest.

[arp242]

I don't disagree that round-tripping comments can be very useful, but I don't really see what the advantage would be to add this to the specification? It's not part of the Go specification either for example: it's just an implementation detail of the Go toolchain.

And for a lot of use case preserving comments isn't important at all.

[pradyunsg]

I don't think this needs to be added to the specification. FWIW, there is at least https://pypi.org/project/tomlkit/ already, that claims to be style preserving TOML encoder/decoder (I've never actually used it, to know how good a job it does) -- basically, this is achievable without anything explicit about this in the specification, and as @arp242 has noted already, there's lots of use cases where preserving comments and round-tripping behaviours are not required.

If there's a bunch of such parser libraries and their authors reckon that it would be useful to have a common specification for how style preservation should work with TOML, we can look into this then. Otherwise, we're just specifying things in thin air with no binding effects whatsoever and I'd prefer to defer this till then.