This is an automated email from the ASF dual-hosted git repository.
lostluck pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/beam.git
The following commit(s) were added to refs/heads/master by this push:
new 7459a91bd05 Improve docstrings for coder.RegisterCoder and
NewCustomCoder (#40050)
7459a91bd05 is described below
commit 7459a91bd0586bfa6c04139c8b6b783040039c5a
Author: Nitin Ware <[email protected]>
AuthorDate: Thu Sep 17 21:13:52 2026 -0500
Improve docstrings for coder.RegisterCoder and NewCustomCoder (#40050)
Adds explicit encoder/decoder function signature documentation to
coder.RegisterCoder, matching the signatures already documented on the
top-level beam.RegisterCoder wrapper. NewCustomCoder now points at the
same signature spec.
Addresses #21930
---
sdks/go/pkg/beam/core/graph/coder/coder.go | 4 ++++
sdks/go/pkg/beam/core/graph/coder/registry.go | 25 +++++++++++++++++++++++++
2 files changed, 29 insertions(+)
diff --git a/sdks/go/pkg/beam/core/graph/coder/coder.go
b/sdks/go/pkg/beam/core/graph/coder/coder.go
index f5f7aa2d757..b5218258819 100644
--- a/sdks/go/pkg/beam/core/graph/coder/coder.go
+++ b/sdks/go/pkg/beam/core/graph/coder/coder.go
@@ -142,6 +142,10 @@ func validateDecoder(t reflect.Type, decode any) error {
// NewCustomCoder creates a coder for the supplied parameters defining a
// particular encoding strategy.
+//
+// encode and decode must be functions matching one of the signatures
documented
+// on RegisterCoder. NewCustomCoder returns an error if either function fails
+// signature validation.
func NewCustomCoder(id string, t reflect.Type, encode, decode any)
(*CustomCoder, error) {
if err := validateEncoder(t, encode); err != nil {
return nil, errors.WithContext(err, "NewCustomCoder")
diff --git a/sdks/go/pkg/beam/core/graph/coder/registry.go
b/sdks/go/pkg/beam/core/graph/coder/registry.go
index 05d211898df..b24439f8f1f 100644
--- a/sdks/go/pkg/beam/core/graph/coder/registry.go
+++ b/sdks/go/pkg/beam/core/graph/coder/registry.go
@@ -44,6 +44,31 @@ var (
// over to check if element types implement them.
//
// Repeated registrations of the same type overrides prior ones.
+//
+// The enc and dec arguments must be functions matching one of the following
+// signatures, where T is the user type registered (the concrete type
+// represented by t, or an interface implemented by encoded values):
+//
+// Supported encoder signatures:
+//
+// func(T) []byte
+// func(reflect.Type, T) []byte
+// func(T) ([]byte, error)
+// func(reflect.Type, T) ([]byte, error)
+//
+// Supported decoder signatures:
+//
+// func([]byte) T
+// func(reflect.Type, []byte) T
+// func([]byte) (T, error)
+// func(reflect.Type, []byte) (T, error)
+//
+// The optional leading reflect.Type parameter is set to the concrete element
+// type at coder construction time; it lets a single (enc, dec) pair serve
+// multiple types (for example, when t is an interface).
+//
+// Passing a function that does not match one of these signatures will cause
+// RegisterCoder to panic.
func RegisterCoder(t reflect.Type, enc, dec any) {
if _, err := NewCustomCoder(t.String(), t, enc, dec); err != nil {
panic(errors.Wrapf(err, "RegisterCoder failed for type %v", t))
