docs: align every document with the reviewed behaviour

Assisted-by: GLM 5.3

docs/API.md

@@ -105,7 +105,7 @@ Encode options:
 | `InlineTables(threshold int)` | `0` | write a sub-table inline when its single-line form is at most `threshold` bytes |
 | `EmitFieldComments(v bool)` | off | print the `comment=` tag option of a field above its line or header |
 
-### `func ParseAs[T any](data []byte) (T, error)`
+### `func ParseAs[T any](data []byte, opts ...UnmarshalOption) (T, error)`
 
 The generic shorthand for `Unmarshal` with a destination variable:
 
@@ -125,7 +125,8 @@ that is not a struct warms nothing.
 ### `func Statements(r io.Reader) iter.Seq2[Statement, error]`
 
 Iterates the top-level statements of the document r carries, in written
-order: key/value statements, a `[table]` header as one statement carrying
+order: key/value statements, a value array or an inline table among them as
+one statement whatever it holds, a `[table]` header as one statement carrying
 its `Table` node, and an `[[array of tables]]` as one statement per element
 with the element's node and its `Index`. Iteration stops at the first error
 and at a false yield, so a caller looking for one section reads no further.
@@ -223,11 +224,7 @@ introduced:
 and no surrounding space, so `# note` is stored as `note` and a bare `#` as
 `""`.
 
-A `Document` is not a value to marshal: `Marshal` writes values, so it refuses
-one and points at `doc.Map()`. Writing a document back, with its order and its
-comments, belongs with the editing API.
-
-### `func Unmarshal(data []byte, v any) error`
+### `func Unmarshal(data []byte, v any, opts ...UnmarshalOption) error`
 
 Parses `data` and stores the result in the value pointed to by `v`, typically a
 pointer to a struct or to `map[string]any`. Equivalent to
@@ -240,11 +237,11 @@ if err := interpres.Unmarshal(data, &cfg); err != nil {
 }
 ```
 
-### `func UnmarshalContext(ctx context.Context, data []byte, v any) error`
+### `func UnmarshalContext(ctx context.Context, data []byte, v any, opts ...UnmarshalOption) error`
 
 The cancellable variant of `Unmarshal`.
 
-### `func Marshal(v any) ([]byte, error)`
+### `func Marshal(v any, opts ...MarshalOption) ([]byte, error)`
 
 Encodes a `struct` or `map[string]V` value, or a non-nil pointer to one, into a
 TOML document. The emission rules are in the [Encoding](#encoding) section
@@ -254,12 +251,12 @@ below. Equivalent to `MarshalContext(context.Background(), v)`.
 out, err := interpres.Marshal(cfg)
 ```
 
-### `func MarshalContext(ctx context.Context, v any) ([]byte, error)`
+### `func MarshalContext(ctx context.Context, v any, opts ...MarshalOption) ([]byte, error)`
 
 The cancellable variant of `Marshal`. The context is checked before any work
 and every 64 fields during the reflection walk.
 
-### `func MarshalAppend(buf []byte, v any) ([]byte, error)`
+### `func MarshalAppend(buf []byte, v any, opts ...MarshalOption) ([]byte, error)`
 
 Appends the TOML encoding of `v` to `buf` and returns the extended buffer, the
 shape `json.MarshalAppend` has. A failed encoding leaves `buf` untouched.
@@ -525,9 +522,9 @@ through the ordinary assignment rules, so every conversion, hook and error the
 path is pinned by a differential fuzz target that decodes every generated
 document both ways and compares the results.
 
-A document or destination the direct skeleton cannot model — an unknown table
+A document or destination the direct skeleton cannot model (an unknown table
 under strictness it must sink, a hook that needs the whole parsed value, an
-embedded map filler — falls back to the tree path and reruns, so the
+embedded map filler) falls back to the tree path and reruns, so the
 observable behaviour is always the tree path's, exactly. Nothing changes for
 `Parse`, `ParseMap` or the document API: the tree remains theirs.
 
@@ -561,8 +558,10 @@ sequenceDiagram
 ### Input constraints
 
 `Marshal` and `MarshalWrite` accept a `struct`, a `map[string]V`, or a
-non-nil pointer to one, where `V` is any value `Marshal` itself understands. A
-different top-level value fails:
+non-nil pointer to one, where `V` is any value `Marshal` itself understands.
+An `OrderedMap` and a `Document` are accepted as themselves: the first in its
+written key order, the second written back as it stands. A different
+top-level value fails:
 
 | Input | Error |
 |---|---|
@@ -736,7 +735,7 @@ across a round-trip.
 
 A nil slice is always omitted. An empty (length 0) array of tables is always
 omitted, because TOML forbids an empty `[[a]]`. Other empty arrays emit as
-`key = []` by default; `OmitEmptyArrays()` skips them as well, so
+`key = []` by default; `OmitEmptyArrays(true)` skips them as well, so
 `[]string{}` is treated like a nil slice.
 
 ### Long strings
@@ -863,7 +862,7 @@ encoding/json/v2 made current, with the differences TOML asks for:
 | `encoding.TextMarshaler`, `TextUnmarshaler` | honoured, the same | a type that renders itself as text becomes a TOML string, both ways |
 | `*json.UnmarshalTypeError` | `*DecodeError` | the path is segments with a `String()` renderer, not a dotted string |
 | `*json.SyntaxError` | `*SyntaxError` | the TOML error adds the byte `Offset` and the `Column` to the line |
-| context support | `*Context` variants of every entry point | encoding/json has none |
+| context support | `*Context` variants of the parse, decode and marshal entries | encoding/json has none |
 
 ## Types