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. Trailing 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. Trailing comment appear at the end of the line after an element and are limited to one per line.

# leading comment1
# leading comment2
key = "value" # trailing 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" # trailing 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 # trailing comment

# leading comment
# leading comment

# leading comment
# leading comment
key2 = 2 # trailing comment

# dangling comment
# dangling comment

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

# dangling comment
# dangling comment

# leading comment
# leading comment
key1 = 1 # trailing comment

# leading comment
# leading comment

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

  # leading comment
  # leading comment

  # leading comment
  # leading comment
  "value2", # trailing comment

  # dangling comment
  # dangling comment
  
  # dangling comment
  # dangling comment
] # trailing 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", # trailing comment

  # leading comment
  # leading comment

  # leading comment
  # leading comment
  key2 = "value2" # trailing comment
  # leading comment

  # leading comment
  # leading comment
  , # trailing comment
  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment
} # trailing 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  # trailing comment
# leading comment
# leading comment
# leading comment
# leading comment
key2 = 2  # trailing comment

# dangling comment
# dangling comment

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

# dangling comment
# dangling comment

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

  # leading comment
  # leading comment
  "value1",  # trailing comment
  # leading comment
  # leading comment
  # leading comment
  # leading comment
  "value2",  # trailing comment

  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment
]  # trailing 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",  # trailing comment
  # leading comment
  # leading comment
  # leading comment
  # leading comment
  key2 = "value2"  # trailing comment
  # leading comment
  # leading comment
  # leading comment
  ,  # trailing comment
  # dangling comment
  # dangling comment

  # dangling comment
  # dangling comment
}  # trailing comment

# dangling comment
# dangling comment

# dangling comment

Through this intelligent comment interpretation, Tombi enables automatic sorting 🚀

← Magic Trailing CommaJson Schema →