From 45520d5a11472f350d6e988a3671ad86f5581843 Mon Sep 17 00:00:00 2001
From: Jack Christensen <jack@jackchristensen.com>
Date: Wed, 14 Jun 2023 08:27:04 -0500
Subject: [PATCH] Document pgtype.Map and pgtype.Type are immutable after
 registration

---
 pgtype/pgtype.go | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/pgtype/pgtype.go b/pgtype/pgtype.go
index 17772024..2672ba00 100644
--- a/pgtype/pgtype.go
+++ b/pgtype/pgtype.go
@@ -147,7 +147,7 @@ const (
 	BinaryFormatCode = 1
 )
 
-// A Codec converts between Go and PostgreSQL values.
+// A Codec converts between Go and PostgreSQL values. A Codec must not be mutated after it is registered with a Map.
 type Codec interface {
 	// FormatSupported returns true if the format is supported.
 	FormatSupported(int16) bool
@@ -178,6 +178,7 @@ func (e *nullAssignmentError) Error() string {
 	return fmt.Sprintf("cannot assign NULL to %T", e.dst)
 }
 
+// Type represents a PostgreSQL data type. It must not be mutated after it is registered with a Map.
 type Type struct {
 	Codec Codec
 	Name  string
@@ -244,6 +245,7 @@ func NewMap() *Map {
 	}
 }
 
+// RegisterType registers a data type with the Map. t must not be mutated after it is registered.
 func (m *Map) RegisterType(t *Type) {
 	m.oidToType[t.OID] = t
 	m.nameToType[t.Name] = t
@@ -275,6 +277,7 @@ func (m *Map) RegisterDefaultPgType(value any, name string) {
 	}
 }
 
+// TypeForOID returns the Type registered for the given OID. The returned Type must not be mutated.
 func (m *Map) TypeForOID(oid uint32) (*Type, bool) {
 	if dt, ok := m.oidToType[oid]; ok {
 		return dt, true
@@ -284,6 +287,7 @@ func (m *Map) TypeForOID(oid uint32) (*Type, bool) {
 	return dt, ok
 }
 
+// TypeForName returns the Type registered for the given name. The returned Type must not be mutated.
 func (m *Map) TypeForName(name string) (*Type, bool) {
 	if dt, ok := m.nameToType[name]; ok {
 		return dt, true
@@ -303,7 +307,8 @@ func (m *Map) buildReflectTypeToType() {
 }
 
 // TypeForValue finds a data type suitable for v. Use RegisterType to register types that can encode and decode
-// themselves. Use RegisterDefaultPgType to register that can be handled by a registered data type.
+// themselves. Use RegisterDefaultPgType to register that can be handled by a registered data type.  The returned Type
+// must not be mutated.
 func (m *Map) TypeForValue(v any) (*Type, bool) {
 	if m.reflectTypeToType == nil {
 		m.buildReflectTypeToType()