Adding comments to JSON configuration?

[xobs]

Description

With TCL files being Not Recommended for New Designs (NRND), the way forward appears to rely on JSON files.

There are a number of configurations that I would like to annotate, either because they are important for later steps (e.g. power nets via blackboxed macros) or because they have a range of values that a user can select that will produce a valid design (e.g. area or density).

However, adding a Javascript comment appears to break the flow.

What is the recommended way to add a comment in a JSON configuration file?

Proposal

The documentation should suggest the appropriate way of documenting configuration choices, preferrably within the JSON file itself.

[donn]

The JSON format does not support comments, other than a number of extensions such as Microsoft's JSONC and JSON5 which both compete (and the target of some light reading material: https://stackoverflow.com/questions/29959191/how-to-parse-json-file-with-c-style-comments).

I'd also ruled out YAML for config files for a different reason: #1294

I do recognize the need for comments though. I'm leaning towards JSONC, but the problem is Microsoft only officially offers a Node.js parser: https://github.com/microsoft/node-jsonc-parser, and all the Python solutions I've found are just hacky, regex-based solutions. (I guess I can write a parser.)

Meanwhile, JSON5 has a more mature library ecosystem, but greatly deviates from the JSON standard- and the same complaints I have for YAML mostly apply.

So I have a lot to consider and I'm just leaning towards JSONC with a custom parser. 🙃

[xobs]

My solution so far has been to add a fake key above the node in question called "comment" with a value that's the acutal comment content. It seems to do the trick, though my editor is not fond of the duplicate keys.