Explain nesting and adding comments to documentation

[danilo-bc]

From the Wikipedia example on TOML (https://en.wikipedia.org/wiki/TOML#Example) it is possible to nest tags by adding the dot operator, as in [servers], [servers.alpha], [servers.beta], as well as adding comments to a TOML file.

I couldn't find the documentation for these features in this package's doc page (https://docs.julialang.org/en/v1/stdlib/TOML/)

I suppose the features are already built-in and only require explaining.

If not, is there any reason why they are not implemented?

[KristofferC]

Hm, I am not sure it makes sense to duplicate the full TOML spec in the documentation for the specific TOML parser. It seems better to just read the official docs for that (https://toml.io/en/).

[danilo-bc]

OK, but tags are implicitly defined in this package as dictionary tags. The TOML specification is language agnostic, but the way we have to organize variables in Julia to write out a valid TOML file is not.

It is not about duplicating the full TOML spec, but explaining how Julia constructs (dictionaries, arrays) should be organized so that you can TOML.print into a valid format. i.e.: How do I write a comment using TOML.print? How would I write the example from the Wiki page, including the nested tags?

[KristofferC]

I see, it is about output format.

There are currently only a few formatting options for the output. Comments for example are not written.

[danilo-bc]

Yes. And also the fact that the sample data given in Julia's Docs

[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]

Cannot be reproduced by simply reading the following example and altering variables, because it does not illustrate how to write down a tag like [database]

julia> using TOML

julia> data = Dict(
          "names" => ["Julia", "Julio"],
          "age" => [10, 20],
       );

<CODE REMOVED FOR BRIEFNESS>

julia> TOML.parsefile(fname)
Dict{String, Any} with 2 entries:
  "names" => ["Julia", "Julio"]
  "age"   => [10, 20]

By trial and error I found out that I can create tags by creating a Dict within a Dict with the tag name being the key.

[StefanKarpinski]

I'm not really following the issue. Is it that it was unclear that the top-level structure would be a Dict?

[danilo-bc]

Yes, it's in that sense. TOML has comments, tags and key-value pairs (something = "value"). The "names-age" example in the Julia docs covers key-value pairs.

I feel it lacks documentation on how to write comments, tags, and how to nest tags.