GODRIVER-2886 Provide more detailed deprecation notes for BSON codecs. (

#1551)

bson/bsoncodec/array_codec.go

@@ -15,16 +15,15 @@ import (
 
 // ArrayCodec is the Codec used for bsoncore.Array values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// ArrayCodec registered.
+// Deprecated: ArrayCodec will not be directly accessible in Go Driver 2.0.
 type ArrayCodec struct{}
 
 var defaultArrayCodec = NewArrayCodec()
 
 // NewArrayCodec returns an ArrayCodec.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// ArrayCodec registered.
+// Deprecated: NewArrayCodec will not be available in Go Driver 2.0. See
+// [ArrayCodec] for more details.
 func NewArrayCodec() *ArrayCodec {
 	return &ArrayCodec{}
 }

bson/bsoncodec/byte_slice_codec.go

@@ -17,13 +17,28 @@ import (
 
 // ByteSliceCodec is the Codec used for []byte values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// ByteSliceCodec registered.
+// Deprecated: ByteSliceCodec will not be directly configurable in Go Driver
+// 2.0. To configure the byte slice encode and decode behavior, use the
+// configuration methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
+// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the byte slice
+// encode and decode behavior for a mongo.Client, use
+// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
+//
+// For example, to configure a mongo.Client to encode nil byte slices as empty
+// BSON binary values, use:
+//
+//	opt := options.Client().SetBSONOptions(&options.BSONOptions{
+//	    NilByteSliceAsEmpty: true,
+//	})
+//
+// See the deprecation notice for each field in ByteSliceCodec for the
+// corresponding settings.
 type ByteSliceCodec struct {
 	// EncodeNilAsEmpty causes EncodeValue to marshal nil Go byte slices as empty BSON binary values
 	// instead of BSON null.
 	//
-	// Deprecated: Use bson.Encoder.NilByteSliceAsEmpty instead.
+	// Deprecated: Use bson.Encoder.NilByteSliceAsEmpty or options.BSONOptions.NilByteSliceAsEmpty
+	// instead.
 	EncodeNilAsEmpty bool
 }
 
@@ -38,8 +53,8 @@ var (
 
 // NewByteSliceCodec returns a ByteSliceCodec with options opts.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// ByteSliceCodec registered.
+// Deprecated: NewByteSliceCodec will not be available in Go Driver 2.0. See
+// [ByteSliceCodec] for more details.
 func NewByteSliceCodec(opts ...*bsonoptions.ByteSliceCodecOptions) *ByteSliceCodec {
 	byteSliceOpt := bsonoptions.MergeByteSliceCodecOptions(opts...)
 	codec := ByteSliceCodec{}

bson/bsoncodec/empty_interface_codec.go

@@ -17,13 +17,27 @@ import (
 
 // EmptyInterfaceCodec is the Codec used for interface{} values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// EmptyInterfaceCodec registered.
+// Deprecated: EmptyInterfaceCodec will not be directly configurable in Go
+// Driver 2.0. To configure the empty interface encode and decode behavior, use
+// the configuration methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
+// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the empty interface
+// encode and decode behavior for a mongo.Client, use
+// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
+//
+// For example, to configure a mongo.Client to unmarshal BSON binary field
+// values as a Go byte slice, use:
+//
+//	opt := options.Client().SetBSONOptions(&options.BSONOptions{
+//	    BinaryAsSlice: true,
+//	})
+//
+// See the deprecation notice for each field in EmptyInterfaceCodec for the
+// corresponding settings.
 type EmptyInterfaceCodec struct {
 	// DecodeBinaryAsSlice causes DecodeValue to unmarshal BSON binary field values that are the
 	// "Generic" or "Old" BSON binary subtype as a Go byte slice instead of a primitive.Binary.
 	//
-	// Deprecated: Use bson.Decoder.BinaryAsSlice instead.
+	// Deprecated: Use bson.Decoder.BinaryAsSlice or options.BSONOptions.BinaryAsSlice instead.
 	DecodeBinaryAsSlice bool
 }
 
@@ -38,8 +52,8 @@ var (
 
 // NewEmptyInterfaceCodec returns a EmptyInterfaceCodec with options opts.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// EmptyInterfaceCodec registered.
+// Deprecated: NewEmptyInterfaceCodec will not be available in Go Driver 2.0. See
+// [EmptyInterfaceCodec] for more details.
 func NewEmptyInterfaceCodec(opts ...*bsonoptions.EmptyInterfaceCodecOptions) *EmptyInterfaceCodec {
 	interfaceOpt := bsonoptions.MergeEmptyInterfaceCodecOptions(opts...)
 

bson/bsoncodec/map_codec.go

@@ -21,25 +21,40 @@ var defaultMapCodec = NewMapCodec()
 
 // MapCodec is the Codec used for map values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// MapCodec registered.
+// Deprecated: MapCodec will not be directly configurable in Go Driver 2.0. To
+// configure the map encode and decode behavior, use the configuration methods
+// on a [go.mongodb.org/mongo-driver/bson.Encoder] or
+// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the map encode and
+// decode behavior for a mongo.Client, use
+// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
+//
+// For example, to configure a mongo.Client to marshal nil Go maps as empty BSON
+// documents, use:
+//
+//	opt := options.Client().SetBSONOptions(&options.BSONOptions{
+//	    NilMapAsEmpty: true,
+//	})
+//
+// See the deprecation notice for each field in MapCodec for the corresponding
+// settings.
 type MapCodec struct {
 	// DecodeZerosMap causes DecodeValue to delete any existing values from Go maps in the destination
 	// value passed to Decode before unmarshaling BSON documents into them.
 	//
-	// Deprecated: Use bson.Decoder.ZeroMaps instead.
+	// Deprecated: Use bson.Decoder.ZeroMaps or options.BSONOptions.ZeroMaps instead.
 	DecodeZerosMap bool
 
 	// EncodeNilAsEmpty causes EncodeValue to marshal nil Go maps as empty BSON documents instead of
 	// BSON null.
 	//
-	// Deprecated: Use bson.Encoder.NilMapAsEmpty instead.
+	// Deprecated: Use bson.Encoder.NilMapAsEmpty or options.BSONOptions.NilMapAsEmpty instead.
 	EncodeNilAsEmpty bool
 
 	// EncodeKeysWithStringer causes the Encoder to convert Go map keys to BSON document field name
 	// strings using fmt.Sprintf() instead of the default string conversion logic.
 	//
-	// Deprecated: Use bson.Encoder.StringifyMapKeysWithFmt instead.
+	// Deprecated: Use bson.Encoder.StringifyMapKeysWithFmt or
+	// options.BSONOptions.StringifyMapKeysWithFmt instead.
 	EncodeKeysWithStringer bool
 }
 
@@ -61,8 +76,8 @@ type KeyUnmarshaler interface {
 
 // NewMapCodec returns a MapCodec with options opts.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// MapCodec registered.
+// Deprecated: NewMapCodec will not be available in Go Driver 2.0. See
+// [MapCodec] for more details.
 func NewMapCodec(opts ...*bsonoptions.MapCodecOptions) *MapCodec {
 	mapOpt := bsonoptions.MergeMapCodecOptions(opts...)
 

bson/bsoncodec/pointer_codec.go

@@ -18,17 +18,25 @@ var _ ValueDecoder = &PointerCodec{}
 
 // PointerCodec is the Codec used for pointers.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// PointerCodec registered.
+// Deprecated: PointerCodec will not be directly accessible in Go Driver 2.0. To
+// override the default pointer encode and decode behavior, create a new registry
+// with [go.mongodb.org/mongo-driver/bson.NewRegistry] and register a new
+// encoder and decoder for pointers.
+//
+// For example,
+//
+//	reg := bson.NewRegistry()
+//	reg.RegisterKindEncoder(reflect.Ptr, myPointerEncoder)
+//	reg.RegisterKindDecoder(reflect.Ptr, myPointerDecoder)
 type PointerCodec struct {
 	ecache typeEncoderCache
 	dcache typeDecoderCache
 }
 
 // NewPointerCodec returns a PointerCodec that has been initialized.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// PointerCodec registered.
+// Deprecated: NewPointerCodec will not be available in Go Driver 2.0. See
+// [PointerCodec] for more details.
 func NewPointerCodec() *PointerCodec {
 	return &PointerCodec{}
 }

bson/bsoncodec/slice_codec.go

@@ -20,8 +20,22 @@ var defaultSliceCodec = NewSliceCodec()
 
 // SliceCodec is the Codec used for slice values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// SliceCodec registered.
+// Deprecated: SliceCodec will not be directly configurable in Go Driver 2.0. To
+// configure the slice encode and decode behavior, use the configuration methods
+// on a [go.mongodb.org/mongo-driver/bson.Encoder] or
+// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the slice encode and
+// decode behavior for a mongo.Client, use
+// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
+//
+// For example, to configure a mongo.Client to marshal nil Go slices as empty
+// BSON arrays, use:
+//
+//	opt := options.Client().SetBSONOptions(&options.BSONOptions{
+//	    NilSliceAsEmpty: true,
+//	})
+//
+// See the deprecation notice for each field in SliceCodec for the corresponding
+// settings.
 type SliceCodec struct {
 	// EncodeNilAsEmpty causes EncodeValue to marshal nil Go slices as empty BSON arrays instead of
 	// BSON null.
@@ -32,8 +46,8 @@ type SliceCodec struct {
 
 // NewSliceCodec returns a MapCodec with options opts.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// SliceCodec registered.
+// Deprecated: NewSliceCodec will not be available in Go Driver 2.0. See
+// [SliceCodec] for more details.
 func NewSliceCodec(opts ...*bsonoptions.SliceCodecOptions) *SliceCodec {
 	sliceOpt := bsonoptions.MergeSliceCodecOptions(opts...)
 

bson/bsoncodec/string_codec.go

@@ -17,8 +17,16 @@ import (
 
 // StringCodec is the Codec used for string values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// StringCodec registered.
+// Deprecated: StringCodec will not be directly accessible in Go Driver 2.0. To
+// override the default string encode and decode behavior, create a new registry
+// with [go.mongodb.org/mongo-driver/bson.NewRegistry] and register a new
+// encoder and decoder for strings.
+//
+// For example,
+//
+//	reg := bson.NewRegistry()
+//	reg.RegisterKindEncoder(reflect.String, myStringEncoder)
+//	reg.RegisterKindDecoder(reflect.String, myStringDecoder)
 type StringCodec struct {
 	// DecodeObjectIDAsHex specifies if object IDs should be decoded as their hex representation.
 	// If false, a string made from the raw object ID bytes will be used. Defaults to true.
@@ -38,8 +46,8 @@ var (
 
 // NewStringCodec returns a StringCodec with options opts.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// StringCodec registered.
+// Deprecated: NewStringCodec will not be available in Go Driver 2.0. See
+// [StringCodec] for more details.
 func NewStringCodec(opts ...*bsonoptions.StringCodecOptions) *StringCodec {
 	stringOpt := bsonoptions.MergeStringCodecOptions(opts...)
 	return &StringCodec{*stringOpt.DecodeObjectIDAsHex}

bson/bsoncodec/struct_codec.go

@@ -60,16 +60,30 @@ type Zeroer interface {
 
 // StructCodec is the Codec used for struct values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// StructCodec registered.
+// Deprecated: StructCodec will not be directly configurable in Go Driver 2.0.
+// To configure the struct encode and decode behavior, use the configuration
+// methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
+// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the struct encode
+// and decode behavior for a mongo.Client, use
+// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
+//
+// For example, to configure a mongo.Client to omit zero-value structs when
+// using the "omitempty" struct tag, use:
+//
+//	opt := options.Client().SetBSONOptions(&options.BSONOptions{
+//	    OmitZeroStruct: true,
+//	})
+//
+// See the deprecation notice for each field in StructCodec for the corresponding
+// settings.
 type StructCodec struct {
 	cache  sync.Map // map[reflect.Type]*structDescription
 	parser StructTagParser
 
 	// DecodeZeroStruct causes DecodeValue to delete any existing values from Go structs in the
 	// destination value passed to Decode before unmarshaling BSON documents into them.
 	//
-	// Deprecated: Use bson.Decoder.ZeroStructs instead.
+	// Deprecated: Use bson.Decoder.ZeroStructs or options.BSONOptions.ZeroStructs instead.
 	DecodeZeroStruct bool
 
 	// DecodeDeepZeroInline causes DecodeValue to delete any existing values from Go structs in the
@@ -82,7 +96,7 @@ type StructCodec struct {
 	// MyStruct{}) as empty and omit it from the marshaled BSON when the "omitempty" struct tag
 	// option is set.
 	//
-	// Deprecated: Use bson.Encoder.OmitZeroStruct instead.
+	// Deprecated: Use bson.Encoder.OmitZeroStruct or options.BSONOptions.OmitZeroStruct instead.
 	EncodeOmitDefaultStruct bool
 
 	// AllowUnexportedFields allows encoding and decoding values from un-exported struct fields.
@@ -95,7 +109,8 @@ type StructCodec struct {
 	// a duplicate field in the marshaled BSON when the "inline" struct tag option is set. The
 	// default value is true.
 	//
-	// Deprecated: Use bson.Encoder.ErrorOnInlineDuplicates instead.
+	// Deprecated: Use bson.Encoder.ErrorOnInlineDuplicates or
+	// options.BSONOptions.ErrorOnInlineDuplicates instead.
 	OverwriteDuplicatedInlinedFields bool
 }
 
@@ -104,8 +119,8 @@ var _ ValueDecoder = &StructCodec{}
 
 // NewStructCodec returns a StructCodec that uses p for struct tag parsing.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// StructCodec registered.
+// Deprecated: NewStructCodec will not be available in Go Driver 2.0. See
+// [StructCodec] for more details.
 func NewStructCodec(p StructTagParser, opts ...*bsonoptions.StructCodecOptions) (*StructCodec, error) {
 	if p == nil {
 		return nil, errors.New("a StructTagParser must be provided to NewStructCodec")

bson/bsoncodec/time_codec.go

@@ -23,12 +23,26 @@ const (
 
 // TimeCodec is the Codec used for time.Time values.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// TimeCodec registered.
+// Deprecated: TimeCodec will not be directly configurable in Go Driver 2.0.
+// To configure the time.Time encode and decode behavior, use the configuration
+// methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
+// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the time.Time encode
+// and decode behavior for a mongo.Client, use
+// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
+//
+// For example, to configure a mongo.Client to ..., use:
+//
+//	opt := options.Client().SetBSONOptions(&options.BSONOptions{
+//	    UseLocalTimeZone: true,
+//	})
+//
+// See the deprecation notice for each field in TimeCodec for the corresponding
+// settings.
 type TimeCodec struct {
 	// UseLocalTimeZone specifies if we should decode into the local time zone. Defaults to false.
 	//
-	// Deprecated: Use bson.Decoder.UseLocalTimeZone instead.
+	// Deprecated: Use bson.Decoder.UseLocalTimeZone or options.BSONOptions.UseLocalTimeZone
+	// instead.
 	UseLocalTimeZone bool
 }
 
@@ -42,8 +56,8 @@ var (
 
 // NewTimeCodec returns a TimeCodec with options opts.
 //
-// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
-// TimeCodec registered.
+// Deprecated: NewTimeCodec will not be available in Go Driver 2.0. See
+// [TimeCodec] for more details.
 func NewTimeCodec(opts ...*bsonoptions.TimeCodecOptions) *TimeCodec {
 	timeOpt := bsonoptions.MergeTimeCodecOptions(opts...)