[FEAT] Add structured comments support for JSON writting

[CarterLi]

Is your feature request related to a problem? Please describe. People ask for documentation... Even if I have provided JSON schema support for my config file, they are still asking, especially those Linux fundamentalists. They don't use vscode or helix that supports JSON schema natively, nor do they want to install a plugin for their vim. They just use plain vim or nano, ignore the "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json" line at the beginning of config file and complain on the Internet that fastfetch's configuration is overwhelmingly more complex than neofetch's.

Describe the solution you'd like I'd like to add comments in the generated JSONC file, for example

{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json", // JSON schema definition, use vscode or helix to make it work
  "logo": { // Logo configuration
    "type": "auto", // Set logo type. "auto": auto detection based on source; "builtin": print built-in ASCII logo, ...
    "source": "" // Set the source file of the logo, or built-in ASCII art name
  }
}

Each comment are attached to one object key, and one key can attach only one comment. When printing:

• If YYJSON_WRITE_PRETTY(_TWO_SPACES) is specified, a line comment (//) can be either printed at the end of the same line of the attached key ( see the code above ), or be printed at the line before the attached key:

{
  // This comment is attached to key `$schema`, so it's printed before key `$schema` with the key's indentation
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  // The comment attached to key `logo`
  "logo": {
    // The comment attached to key `logo.type`
    "type": "auto",
    // The comment attached to key `logo.source`
    "source": ""
  }
}

• If YYJSON_WRITE_PRETTY(_TWO_SPACES) is not specified ( I think this is less useful when users want to print comments ), an inline comment (/* */) will be added right before / after the key, for example:

{"$schema"/*The comment attached to key `$schema`*/:"https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json","logo"/*The comment attached to key `logo`*/:{"type"/*The comment attached to key `logo.type`...*/:"auto"}}

Proposed API:

bool yyjson_mut_obj_add_val_with_comment(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, yyjson_mut_val *val, const char* str); // str is a dynamic string that should be copied into yyjson doc
// And other `yyjson_mut_obj_add_*_with_comment` friends

Describe alternatives you've considered Comments can be attached to any yyjson_mut_val. It's more generic but more complex and I don't think it has many use cases. For now, I think attaching to object keys only is enough.

Additional context N/A

[CarterLi]

For comments contain \n:

yyjson_mut_obj_add_uint_with_comment(doc, obj, "key", 1, "Title:\n    Line 1\n    Line 2\n    Line 3

Should generate

1. YYJSON_WRITE_PRETTY(_TWO_SPACES) enabled with comments being printed in separate line

{
  // Title: (there is always a white space between `//` and comment string)
  //     Line 1 (1+4=5 white spaces)
  //     Line 2
  //     Line 3
  "key": 1,
  "others": 2
}

2. YYJSON_WRITE_PRETTY(_TWO_SPACES) enabled with comments being printed in the same line

{
  "key": 1, // Title:
            //     Line 1 (keep indentation of the first line)
            //     Line 2
            //     Line 3
  "others": 2
}

3. YYJSON_WRITE_PRETTY(_TWO_SPACES) disabled with comments being printed after key

{"key"/*Title:
    Line 1
    Line 2
    Line 3*/:1,"others":2}

4. YYJSON_WRITE_PRETTY(_TWO_SPACES) disabled with comments being printed before key

{/*Title:
    Line 1
    Line 2
    Line 3*/"key":1,"others":2}

[ibireme]

Thanks for the suggestion.

There was an earlier discussion about preserving comments: https://github.com/ibireme/yyjson/issues/121 The main limitation is that json_val is a very compact structure, and there's no room to store comments directly.

I've been reconsidering the idea, and it might be possible to support this by adding a separate structure in json_doc to associate comments with individual json_val. I'll try this approach later.

[CarterLi]

it might be possible to support this by adding a separate structure in json_doc to associate comments with individual json_val. I'll try this approach later.

Thanks.

I'm only asking comments support for writing. I don't think preserving comments when reading JSON string is useful, as comments are not structured, and they won't follow their main nodes' position when reformatted.