improve strategy for comment output

[rogpeppe]

There are a number of open issues regarding comments:

• cmd/fmt: comma appended to comment instead of list element #1478
• cmd/fmt: single import and comment combined #1447
• cmd/cue: fmt converts tabs to spaces in comments #1040
• cue fix tries to align comments inside braces with those outside, causing weird field indentation #1006
• cue fmt indents top-level comments #722
• Cue fmt drags comments into import block #720

Most of these are to do with comment formatting, but there's a deeper issue here: what should happen to comments when we apply unification to CUE values?

Here's a simple example to illustrate current behaviour:

// Comment 1
a: 1

// Comment 2
a: 1

// Comment 3
a: 1

Running cue def on that results in the following output:

// Comment 1

// Comment 2

// Comment 3
a: 1

Running cue def again gives:

	// Comment 3
a: 1

This isn't great for a few reasons:

• cue def should probably produce output that doesn't change when run through cue def again.
• The result is dependent on the order of unification. If the three parts are in three separate files, the order of the comments depends on the file names.
• comments are lost the second time cue def is run

There's no obvious "right answer" here. Some possibilities:

1. Don't output comments at all.
2. Keep a single comment only; any additional comments cause the comment to disappear
3. Retain all comments, concatenating comment text from all unifications, sorting by comment text.
4. Provide a way to customize whether a comment is included or not.

Choice 1 is obviously the easiest option, but comments are very useful and if possible it would be good to better than that.

Choice 2 makes for unstable output. If someone adds a comment to a schema, it could cause an important comment on the data to disappear.

Choice 3 results in comments that are a mishmash from different layers in non-obvious order. It's not clear that we actually want all comments anyway. Consider this example. That workflow schema has copious comments that describe how to use the schema, but those aren't very useful on the final result, where we'd prefer to see comments about the final rendered workflow rather than the schema.

Choice 4 could potentially provide the best of both worlds, but leaves open the question of how that customization might work.