docs: align the remaining Decoder and Encoder mentions with the options API
Test / test (push) Successful in 1m41s

Assisted-by: GLM 5.3 Flash
This commit is contained in:
2026-09-22 19:27:12 +02:00
parent 2e61ad0ba9
commit 8f2b26bd33
3 changed files with 12 additions and 14 deletions
+2 -3
View File
@@ -26,7 +26,7 @@ the entire official [toml-test](https://github.com/toml-lang/toml-test) suite:
- **Ordered documents**: `Parse` gives a `*Document` that keeps the key order,
tells an inline table from a header one, and carries the comments; `ParseMap`
gives the plain `map[string]any` tree.
- **Configurable emission**: `Encoder` options for declaration-order output,
- **Configurable emission**: `Marshal` options for declaration-order output,
omitting empty arrays, literal multiline strings, and inlining small
sub-tables.
@@ -54,8 +54,7 @@ just example
```
`just example` runs the tour in `examples/basic`: it decodes an embedded
document into a struct, prints it, and re-encodes it under both `Encoder`
layouts.
document into a struct, prints it, and re-encodes it under both layouts.
## Usage
+6 -6
View File
@@ -547,12 +547,12 @@ sequenceDiagram
participant Caller
participant Unmarshal as Unmarshal
participant Parser as parser
participant Decoder as decoder
participant Decode as decode
Caller->>Unmarshal: data, v
Unmarshal->>Parser: ParseContext(ctx, data)
Parser-->>Unmarshal: tree or *SyntaxError
Unmarshal->>Decoder: decode(tree, reflect value)
Decoder-->>Unmarshal: nil or wrapped field error
Unmarshal->>Parser: targeted parse straight into v
Parser-->>Unmarshal: nil, *SyntaxError, or fallback
Unmarshal->>Decode: tree rerun on fallback
Decode-->>Unmarshal: nil or wrapped field error
Unmarshal-->>Caller: error
```
@@ -647,7 +647,7 @@ parsed as keys of the sub-table.
### Preserving declaration order
`LayoutKindDeclaration` on an `Encoder` walks the entries in declaration order
`Layout(LayoutKindDeclaration)` walks the entries in declaration order
instead, emitting each header immediately before its content:
```go
+4 -5
View File
@@ -35,7 +35,7 @@ strict validation.
| Path | Responsibility |
|---|---|
| `.` (package `interpres`) | The whole library. `interpres.go` declares the exported surface (`Parse`, `Unmarshal`, `Marshal`, the `*Context` variants, `Decoder`, `Encoder`, `Marshaler`, `Unmarshaler`, `SyntaxError`, the local date-time types); everything below it is unexported. |
| `.` (package `interpres`) | The whole library. `interpres.go` declares the exported surface (`Parse`, `Unmarshal`, `Marshal`, the `*Context` variants, the option constructors, `Marshaler`, `Unmarshaler`, `SyntaxError`, the local date-time types); everything below it is unexported. |
| `cmd/interpres-decode` | The toml-test adapter, both directions. Reads TOML on stdin, writes tagged JSON on stdout; with `-encode` it reads tagged JSON and writes TOML. Owns no parsing logic and no emission logic. |
| `examples/basic` | A runnable tour of the API. Documentation in executable form, not part of the library. |
@@ -96,10 +96,9 @@ sequenceDiagram
## State and lifetime
- The exported `Decoder` and `Encoder` hold configuration only. Every
`Decode`, `DecodeContext`, `Marshal` and `MarshalContext` call allocates its
own unexported worker, so a configured type is safe for concurrent use; the
setter methods are not, and must finish before the value is shared.
- The option values are stateless: every `Unmarshal`, `Marshal` and their
variants apply their own options into a per-call unexported worker, so the
entries are safe for concurrent use.
- The parser is allocated per `ParseContext` call; the parser itself caches
nothing between documents.
- The shared state is a set of caches and pools whose entries are immutable