feat: add field comments, local time zone decoding and in-value cancellation

Assisted-by: GLM 5.3 Flash

encode_test.go

@@ -2234,3 +2234,57 @@ func TestOmitEmptyJSONSemantics(t *testing.T) {
 		t.Errorf("output:\n%q\nwant:\n%q", out, want)
 	}
 }
+
+func TestEmitFieldComments(t *testing.T) {
+	type Cfg struct {
+		Host string `toml:"host,comment=The host to dial"`
+		Port int    `toml:"port,comment=The port to listen on.\nThe default is 8080."`
+		User string `toml:"user"`
+	}
+	cfg := Cfg{Host: "db", Port: 5432, User: "admin"}
+	t.Run("off by default", func(t *testing.T) {
+		out, err := Marshal(cfg)
+		if err != nil {
+			t.Fatal(err)
+		}
+		want := "host = \"db\"\nport = 5432\nuser = \"admin\"\n"
+		if string(out) != want {
+			t.Errorf("output:\n%q", out)
+		}
+	})
+	t.Run("on, the comments print above their lines", func(t *testing.T) {
+		out, err := NewEncoder().EmitFieldComments().Marshal(cfg)
+		if err != nil {
+			t.Fatal(err)
+		}
+		want := "# The host to dial\nhost = \"db\"\n" +
+			"# The port to listen on.\n# The default is 8080.\nport = 5432\n" +
+			"user = \"admin\"\n"
+		if string(out) != want {
+			t.Errorf("output:\n%q\nwant:\n%q", out, want)
+		}
+		var back Cfg
+		if err := Unmarshal(out, &back); err != nil {
+			t.Fatalf("the output does not re-parse: %v", err)
+		}
+		if back != cfg {
+			t.Errorf("round trip = %+v", back)
+		}
+	})
+	t.Run("a table header carries its comment", func(t *testing.T) {
+		type Inner struct {
+			A int `toml:"a,comment=The a"`
+		}
+		type Nested struct {
+			Inner Inner `toml:"inner,comment=The inner table"`
+		}
+		out, err := NewEncoder().EmitFieldComments().Marshal(Nested{Inner: Inner{1}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		want := "# The inner table\n[inner]\n# The a\na = 1\n"
+		if string(out) != want {
+			t.Errorf("output:\n%q\nwant:\n%q", out, want)
+		}
+	})
+}