Status of Single-line and Multiline Comments about j-toml

[LongTengDao]

Yes, of cause I also want to support over-line, "island" and multi-line comments.

The main difficulty I meet, is that there seems no good way to describe which does a comment belong to (while parsing or stringifying). The commens could be too whimsical.

Think about this:

# overall

# a
# a.a
a.a = 1
# a.b
a.b.x = 1
a.b.y = 1
#a.b.z = 1

How would you treat that?

If we just remain the comments, without correct belonging relationship which most likely meeting the writer's intention, then it rarely help, and will break the compatibility when we finally find a good enough rule in the future.

I'm glad to discuss any possible idea, welcome to feedback.

[shawntabrizi]

Yeah, totally understood. The island comments seem to be the hardest to handle here, but I think that you could create a few rules which would capture most situations.

For example, today you only capture inline comments, and drop the rest.

You could also enable a feature where single / multi-line comments are attached to the nearest TOML line below it, and the rest would be dropped just as before.

So using your example above, we would get:

{
    a: {
        a: '1', [commentAbove('a')]: ' a \n a.a',
        b: {
            x: '1', [commentAbove('x')]: ' a.b',
            y: '1'
        }
    }
}

At least in this case, we capture what is arguably the most common kind of comment in the way that is most normally expected. Here we still drop the island comment, and the tricky comment at the end of the file, but this would be a large step forward from what is available today.

And, at the end, I believe more rules like this could be configurable as xOptions, allowing the user to play with the rules for their desired behavior.

[LongTengDao]

I think I need to confirm your final need about comment.

Firstly, @ltd/j-toml support any valid comment parsing; problem is how to remain it when stringify.

Here are two main cases to stringify a TOML document with comments: 1) a table parsed from existing file (which means you only want to change some value, and want to remain the comments without changes); 2) a brand new table with new structure, or change existing comments info.

If only 1st case is usually needed, then the mechanisms can be in black box; if both, then here must be a good enough api, and I need to design it systematically.

[LongTengDao]

# overall

# a
# a.a
a.a = 1
# a.b
a.b.x = 1
a.b.y = 1
#a.b.z = 1

{
    [commentsInThis]: [ [' overall'], [' a',' a.a'], 'a', ['a.b.z = 1'] ],
    a: {
        [commentsInThis]: [ 'a', [' a.b'], 'b' ],
        a: 1,
        b: {
            x: 1,
            y: 1,
        },
    },
}

Does this look good enough? (Won't distinguish over-line comment and "island" comment, which can be designed, but I found it's easy to see mixing up in your samples.)

[shawntabrizi]

@LongTengDao first, thank you for your time to discuss this with me.

I think this might work. As I understand this syntax, you are keeping track of the comments and where they are relative to certain keys. In this case a and b in those commentsInThis refer to the location of the key, and then the comments exist positionally around them.

Ultimately, I would need to test this logic on some of the files by doing parse -> stringify to see the diff, but yes, I think this would already be a big improvement.