# Comments

Read and write comments separately from values. Comment strings do not include the leading `#`.

## End-of-line comments

Use `comments` like a dictionary keyed by entry name. Assign a string to set or replace a comment; `del` removes it.

```python
import tomlrt

doc = tomlrt.loads("""\
[server]
host = "localhost"  # default
port = 8080
""")

server = doc.table("server")
server.comments["port"] = "override with $PORT"
del server.comments["host"]

print(tomlrt.dumps(doc))
```

```toml
[server]
host = "localhost"
port = 8080 # override with $PORT
```

## Comments above an entry

`leading_comments` reads or replaces the comment lines immediately above an entry, with no intervening blank line:

```python
server.leading_comments["port"] = (
    "Port the server listens on.",
    "Defaults to 8080.",
)
```

## Section header comments

Use `header_comment` for a comment on the `[section]` line itself, and `header_leading_comments` for comments immediately above it:

```python
server.header_comment = "HTTP listener"
server.header_leading_comments = ("Server configuration.",)
```

## Array-item comments

Arrays have the same `comments` and `leading_comments` properties, keyed by item index:

```python
tags = doc.array("tags")
tags.comments[0] = "primary"
tags.leading_comments[1] = ("alternate",)
```

## Inline-table comments

TOML 1.1 allows inline tables to span multiple lines and carry comments. Use the same comment properties as for sections:

```python
import tomlrt

doc = tomlrt.loads('pkg = { name = "tomlrt", version = "0.1" }\n')
pkg = doc.table("pkg")
pkg.comments["name"] = "the package name"

print(tomlrt.dumps(doc))
```

```toml
pkg = {
    name = "tomlrt", # the package name
    version = "0.1",
}
```

Adding a comment makes a single-line table or array multi-line automatically. See [Layout](<https://dimbleby.github.io/tomlrt/layout/index.md>) to control this explicitly.

Inline tables have no section header, so the `header_*` properties are not available on them.

## Blank-separated leading blocks

Use `leading_block` or `header_leading_block` to include comments separated by blank lines. These return a tuple of comment strings, with `None` for each blank line. For example:

```toml
[a]
x = 1

# Configuration

[b]
y = 2
```

```python
assert doc["b"].header_leading_block == (None, "Configuration", None)
doc["b"].header_leading_block = ("Configuration", None, "Section b")
```

Comment blocks travel with their entry when copied, moved, or sorted. The document preamble and epilogue stay with the document.

## Document preamble and epilogue

Use `Document.preamble` and `Document.epilogue` for opening and closing file comments. Assignment replaces the whole block; `()` clears it.

```python
doc.preamble = ("Generated by build.py — do not edit.",)
doc.epilogue = ("end of file",)
```

A "preamble" is the document's opening comment paragraph — the run of `# …` lines before the first blank line. Comments below that blank line belong to the first key or section, not the preamble.

The "epilogue" is the comment block after the last entry. It can include blank lines, represented by `None`.