Serialize doc comments

[ShayBox]

This issue existed before the move to toml_edit toml-rs/toml-rs#274
The issue was also brought up to serde serde-rs/serde#1430

It would be a nice feature to write comments for config files, whether it uses serde or a macro
(I think the prior would be the cleanest) 👍

[epage]

Seeing as this was rejected by serde, there isn't room for this to exist in the toml crate which will be focusing on serde support going forward. You can manually set comments via the toml_edit crate, though. Creating a whole new serialization system with derives to handle this would be out of scope though people are welcome to experiment with it.

[ShayBox]

While parsing toml with manual comments is supported, writing to a toml file with comments creates an unreadable corrupted file at worst, or wipes out the comments at best.
Comments are useless, but this is the case for everything that uses serde not just toml.

[epage]

writing to a toml file with comments creates an unreadable corrupted file at worst,

In what way are corrupted files written?

wipes out the comments at best

As I said, toml_edit is an option. It is a format preserving parser / writer. It is used by cargo add to preserve your Cargo.toml while adding or modifying dependency entries.

[ckaran]

Is it possible to add a comment type as another variant to the Value enum? I too would like to be able to serialize comments into the TOML files that I output as TOML is meant to be human-readable.

Mainly, I want to be able to produce partially customized files that the reader can read through and customize afterwards. They are partially customized in two ways:

• I have a tool that scans their system to preset options appropriate for them. That means that one size doesn't fit all.
• I want the comments to be in their native language. Once again, one size doesn't fit all.

Thus, the comments are more than just whitespace, they are a necessary feature of the file.

[epage]

Is it possible to add a comment type as another variant to the Value enum? I too would like to be able to serialize comments into the TOML files that I output as TOML is meant to be human-readable.

The toml_edit crate fills this role and adding it won't add a dependency as toml depends on it.

[ckaran]

OK, I just checked it out. I think that will work for my use case. Thank you!

[jyn514]

Just mentioning it here because it took me a while to figure out - the way to add comments with toml_edit is by calling decor_mut on a Formatted Value and then calling Decor::set_prefix with your comment as the argument.

[Notgnoshi]

Just mentioning it here because it took me a while to figure out

Thanks this was very helpful! Here's an example for posterity:

use documented::DocumentedFields;
use serde::Serialize;
use struct_field_names_as_array::FieldNamesAsArray;
use toml_edit::ser::to_document;

/// A test struct
#[derive(Default, DocumentedFields, FieldNamesAsArray, Serialize)]
struct TestMe {
    /// First field
    ///
    /// Second line
    field1: u32,
    /// Second field
    field2: String,
}

let test = TestMe::default();
let mut doc = to_document(&test).unwrap();

for (mut key, _value) in doc.iter_mut() {
    let key_name = key.get().to_owned();
    let decor = key.decor_mut();
    let docstring = TestMe::get_field_comment(key_name).unwrap();

    let mut comment = String::new();
    for line in docstring.lines() {
        let line = if line.is_empty() {
            String::from("#\n")
        } else {
            format!("# {line}\n")
        };
        comment.push_str(&line);
    }
    decor.set_prefix(comment);
}

let actual = doc.to_string();
let expected = "# First field\n#\n# Second line\nfield1 = 0\n# Second field\nfield2 = \"\"\n";
assert_eq!(actual, expected);

[cyqsimon]

@Notgnoshi Thanks for the example. I'm trying to generate a default config file that includes comments, so this is pretty much exactly what I need.

An update on the APIs used here:

1. toml_edit::Key::decor_mut was deprecated, because in the case of a "dotted key" it's ambiguous who the comment "belongs to". What you likely want is leaf_decor_mut. For simple values you likely want leaf_decor_mut; for tables and array of tables you likely want dotted_decor_mut to descend into its value and set the decor there. It's all quite confusing. See Comments between lines in a table are duplicated #673.
2. documented::DocumentedFields::get_field_comment was deprecated in favour of get_field_docs, because the name is more accurate.

---

P.s. It's wild to see what was originally just my own toy crate (documented) being used by actual people. I'm glad you're finding it useful!

[cyqsimon]

And this is what I ended up with. Just thought I'd share it with anyone who needs a simple (well, somewhat simple) and practical example.

[ShayBox]

I've spent two days trying to add doc comment support to my personal config derive macro crate. Getting the comments was easy, especially with the documented crate.

However, I made things harder on myself by trying to use toml_edit for TOML. Working with leaf and dotted decor ended up being much more complex than I needed.

I realize this isn't really what toml_edit was designed for, and my limited understanding of its internals doesn't help. Even after spending $35 in Sonnet 3.5 credits with Cline to analyze toml_edit’s source and various examples above, it couldn't get it right, but it was able to create a line-by-line version that worked perfectly without.

Because of the recursive nature of this, when you change one part of the prefix in one area it would break for recursive areas, and constantly running into deprecated decor that seemed to previously work but now now requires way more work to place the comments exactly where they should be.