docs: add godoc examples, extend the basic example and map encoding/json

Assisted-by: GLM 5.3 Flash

examples/basic/main.go

@@ -8,6 +8,7 @@
 package main
 
 import (
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -39,13 +40,16 @@ admin = false
 
 // Config mirrors the document above. The Server field is a named struct so
 // the reader sees explicit subtable boundaries; Users is a slice of named
-// structs so the array-of-tables path is exercised.
+// structs so the array-of-tables path is exercised. Retries carries the
+// `omitzero` tag option: a zero value of the field's type drops from the
+// output, and a `time.Duration` zero is zero nanoseconds.
 type Config struct {
-	Title    string    `toml:"title"`
-	Launched time.Time `toml:"launched"`
-	Debug    bool      `toml:"debug"`
-	Server   Server    `toml:"server"`
-	Users    []User    `toml:"users"`
+	Title    string        `toml:"title"`
+	Launched time.Time     `toml:"launched"`
+	Debug    bool          `toml:"debug"`
+	Server   Server        `toml:"server"`
+	Users    []User        `toml:"users"`
+	Retries  time.Duration `toml:"retries,omitzero"`
 }
 
 type Server struct {
@@ -147,5 +151,33 @@ func Run(stdout, stderr io.Writer) int {
 	fmt.Fprintf(stdout, "\n--- round-trip --- ok (title=%q, users=%d)\n",
 		roundTripped.Title, len(roundTripped.Users))
 
+	// Typed errors: a decode failure names the key path it failed at, and
+	// errors.AsType reaches the DecodeError to read the path and the cause
+	// separately, without parsing the message text.
+	bad := []byte("[[users]]\nname = \"x\"\nadmin = \"not-a-bool\"\n")
+	var badCfg Config
+	err = interpres.Unmarshal(bad, &badCfg)
+	if err == nil {
+		fmt.Fprintln(stderr, "expected a decode error")
+		return 1
+	}
+	if de, ok := errors.AsType[*interpres.DecodeError](err); ok {
+		fmt.Fprintf(stdout, "\n--- typed error --- path %s: %v\n", de.Path.String(), de.Err)
+	} else {
+		fmt.Fprintln(stderr, "expected a DecodeError")
+		return 1
+	}
+
+	// omitzero: the retries field carries the tag option and a zero duration,
+	// so the re-encoded config above simply has no retries line. Give it a
+	// value and the line appears.
+	cfg.Retries = 30 * time.Second
+	out3, err := interpres.Marshal(cfg)
+	if err != nil {
+		fmt.Fprintln(stderr, "marshal:", err)
+		return 1
+	}
+	fmt.Fprintf(stdout, "\n--- omitzero ---\n%s", out3)
+
 	return 0
 }