Treatment of Comments

Tombi provides sophisticated comment interpretation to support automatic sorting.

While most users will learn how comments are handled by observing the formatter's behavior, this page offers a systematic understanding of Tombi's comment treatment.

Terminology

In TOML files, there are three types of comments:

  1. Leading comments
  2. Tailing comment
  3. Dangling comments

Types 1 and 2 are associated with specific elements. Leading comments appear on the lines before an element and can span multiple consecutive lines. Tailing comment appear at the end of the line after an element and are limited to one per line.

# leading comment1
# leading comment2
key = "value" # tailing comment

Type 3, Dangling comments, are comments that are not associated with any specific element.

# dangling comment1
# dangling comment2

key = "value"

# dangling comment3

# dangling comment4

It is impossible to automatically sort Dangling Comments.

Consider this example:

# dangling comment1

key2 = "value2"

# dangling comment2

# leading comment1
# leading comment2
key1 = "value1" # tailing comment
# dangling comment3

# dangling comment4

When sorting keys in ascending order, key1 should come before key2. But where should dangling comment2 be placed? Before key1 or after key2? Tombi cannot determine which element the comment is intended for.

Should we use AI to interpret the comment content?

No, Tombi solves this problem through a set of special rules.

Limiting the Use of Dangling Comments

The key to Tombi's ability to auto-sort is treating some comments that appear to be Dangling Comments as Leading Comments.

Tombi allows Dangling Comments to be placed before and after key values, and before and after the brackets of arrays and inline tables.

# dangling comment
# dangling comment

key = "value"

# dangling comment
# dangling comment

[table]
# dangling comment
# dangling comment

key = [
  # dangling comment
  # dangling comment
  
  "value",
  
  # dangling comment
  # dangling comment
]

# dangling comment
# dangling comment

[[array_of_table]]
# dangling comment
# dangling comment

key = {
  # dangling comment
  # dangling comment
  
  key = "value"
  
  # dangling comment
  # dangling comment
}

# dangling comment
# dangling comment
🗒️Note

Dangling comments can be separated by blank lines, allowing multiple groups to be placed.

# dangling comment
# dangling comment

# dangling comment
# dangling comment

# dangling comment
# dangling comment
💡Tip

The proposed TOML v1.1.0 specification allows multi-line and trailing commas in Inline Tables.

What happens to dangling comments in other locations?

Merging Leading Comments

Consider a case where comments exist between key values, where dangling comments are not allowed:

key1 = 1

# dangling comment?
# dangling comment?

# dangling comment?
# dangling comment?

key2 = 2

In such cases, Tombi treats these dangling comments as leading comments and removes blank lines between them:

key1 = 1
# dangling comment?
# dangling comment?
# dangling comment?
# dangling comment?
key2 = 2

Through this special pre-processing, Tombi maintains the meaning of comments while enabling automatic sorting.

Summary of Comment Handling

Let's examine a comprehensive example to understand how Tombi handles comments:

# dangling comment
# dangling comment

# leading comment
# leading comment
key1 = 1 # tailing comment

# leading comment
# leading comment

# leading comment
# leading comment
key2 = 2 # tailing comment

# dangling comment
# dangling comment

# leading comment
# leading comment
[table]
# dangling comment

# dangling comment
# dangling comment

# leading comment
# leading comment
key1 = 1 # tailing comment

# leading comment
# leading comment

# leading comment
key2 = [
  # dangling comment
  # dangling comment
  
  # leading comment
  # leading comment
  "value1", # tailing comment

  # leading comment
  # leading comment

  # leading comment
  # leading comment
  "value2", # tailing comment

  # dangling comment
  # dangling comment
  
  # dangling comment
  # dangling comment
] # tailing comment

# dangling comment
# dangling comment

# leading comment
[[array_of_table]]
# dangling comment
# dangling comment

key1 = {
  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment
  
  # leading comment
  # leading comment
  key1 = "value1", # tailing comment

  # leading comment
  # leading comment

  # leading comment
  # leading comment
  key2 = "value2" # tailing comment
  # leading comment

  # leading comment
  # leading comment
  , # tailing comment
  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment
} # tailing comment

# dangling comment
# dangling comment

# dangling comment

After formatting, the comments are rearranged as follows:

# dangling comment
# dangling comment

# leading comment
# leading comment
key1 = 1  # tailing comment
# leading comment
# leading comment
# leading comment
# leading comment
key2 = 2  # tailing comment

# dangling comment
# dangling comment

# leading comment
# leading comment
[table]
# dangling comment

# dangling comment
# dangling comment

# leading comment
# leading comment
key1 = 1  # tailing comment
# leading comment
# leading comment
# leading comment
key2 = [
  # dangling comment
  # dangling comment

  # leading comment
  # leading comment
  "value1",  # tailing comment
  # leading comment
  # leading comment
  # leading comment
  # leading comment
  "value2",  # tailing comment

  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment
]  # tailing comment

# dangling comment
# dangling comment

# leading comment
[[array_of_table]]
# dangling comment
# dangling comment

key1 = {
  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment

  # leading comment
  # leading comment
  key1 = "value1",  # tailing comment
  # leading comment
  # leading comment
  # leading comment
  # leading comment
  key2 = "value2"  # tailing comment
  # leading comment
  # leading comment
  # leading comment
  ,  # tailing comment
  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment
}  # tailing comment

# dangling comment
# dangling comment

# dangling comment

Through this intelligent comment interpretation, Tombi enables automatic sorting 🚀

:schema Directive

Tombi supports embedding JSON Schema information in TOML files, similar to Taplo.

#:schema your-schema.json
key = "value"

During auto-sorting, to ensure the #:schema directive remains at the beginning of the document, Tombi first moves the comment group containing the #:schema directive to the start before performing auto-sorting.

#:schema your-schema.json

key = "value"
← Magic Trailing CommaJson Schema →