Skip to content

Commit 9afea90

Browse files
matthewdalematthewdale
authored
GODRIVER-2886 Provide more detailed deprecation notes for BSON codecs. (#1551)
1 parent 414aa9f commit 9afea90

10 files changed

+166
-50
lines changed

‎bson/bsoncodec/array_codec.go

+3-4
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,15 @@ import (
1515

1616
// ArrayCodec is the Codec used for bsoncore.Array values.
1717
//
18-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
19-
// ArrayCodec registered.
18+
// Deprecated: ArrayCodec will not be directly accessible in Go Driver 2.0.
2019
type ArrayCodec struct{}
2120

2221
var defaultArrayCodec = NewArrayCodec()
2322

2423
// NewArrayCodec returns an ArrayCodec.
2524
//
26-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
27-
// ArrayCodec registered.
25+
// Deprecated: NewArrayCodec will not be available in Go Driver 2.0. See
26+
// [ArrayCodec] for more details.
2827
func NewArrayCodec() *ArrayCodec {
2928
return &ArrayCodec{}
3029
}

‎bson/bsoncodec/byte_slice_codec.go

+20-5
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,28 @@ import (
1717

1818
// ByteSliceCodec is the Codec used for []byte values.
1919
//
20-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
21-
// ByteSliceCodec registered.
20+
// Deprecated: ByteSliceCodec will not be directly configurable in Go Driver
21+
// 2.0. To configure the byte slice encode and decode behavior, use the
22+
// configuration methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
23+
// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the byte slice
24+
// encode and decode behavior for a mongo.Client, use
25+
// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
26+
//
27+
// For example, to configure a mongo.Client to encode nil byte slices as empty
28+
// BSON binary values, use:
29+
//
30+
// opt := options.Client().SetBSONOptions(&options.BSONOptions{
31+
// NilByteSliceAsEmpty: true,
32+
// })
33+
//
34+
// See the deprecation notice for each field in ByteSliceCodec for the
35+
// corresponding settings.
2236
type ByteSliceCodec struct {
2337
// EncodeNilAsEmpty causes EncodeValue to marshal nil Go byte slices as empty BSON binary values
2438
// instead of BSON null.
2539
//
26-
// Deprecated: Use bson.Encoder.NilByteSliceAsEmpty instead.
40+
// Deprecated: Use bson.Encoder.NilByteSliceAsEmpty or options.BSONOptions.NilByteSliceAsEmpty
41+
// instead.
2742
EncodeNilAsEmpty bool
2843
}
2944

@@ -38,8 +53,8 @@ var (
3853

3954
// NewByteSliceCodec returns a ByteSliceCodec with options opts.
4055
//
41-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
42-
// ByteSliceCodec registered.
56+
// Deprecated: NewByteSliceCodec will not be available in Go Driver 2.0. See
57+
// [ByteSliceCodec] for more details.
4358
func NewByteSliceCodec(opts ...*bsonoptions.ByteSliceCodecOptions) *ByteSliceCodec {
4459
byteSliceOpt := bsonoptions.MergeByteSliceCodecOptions(opts...)
4560
codec := ByteSliceCodec{}

‎bson/bsoncodec/empty_interface_codec.go

+19-5
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,27 @@ import (
1717

1818
// EmptyInterfaceCodec is the Codec used for interface{} values.
1919
//
20-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
21-
// EmptyInterfaceCodec registered.
20+
// Deprecated: EmptyInterfaceCodec will not be directly configurable in Go
21+
// Driver 2.0. To configure the empty interface encode and decode behavior, use
22+
// the configuration methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
23+
// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the empty interface
24+
// encode and decode behavior for a mongo.Client, use
25+
// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
26+
//
27+
// For example, to configure a mongo.Client to unmarshal BSON binary field
28+
// values as a Go byte slice, use:
29+
//
30+
// opt := options.Client().SetBSONOptions(&options.BSONOptions{
31+
// BinaryAsSlice: true,
32+
// })
33+
//
34+
// See the deprecation notice for each field in EmptyInterfaceCodec for the
35+
// corresponding settings.
2236
type EmptyInterfaceCodec struct {
2337
// DecodeBinaryAsSlice causes DecodeValue to unmarshal BSON binary field values that are the
2438
// "Generic" or "Old" BSON binary subtype as a Go byte slice instead of a primitive.Binary.
2539
//
26-
// Deprecated: Use bson.Decoder.BinaryAsSlice instead.
40+
// Deprecated: Use bson.Decoder.BinaryAsSlice or options.BSONOptions.BinaryAsSlice instead.
2741
DecodeBinaryAsSlice bool
2842
}
2943

@@ -38,8 +52,8 @@ var (
3852

3953
// NewEmptyInterfaceCodec returns a EmptyInterfaceCodec with options opts.
4054
//
41-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
42-
// EmptyInterfaceCodec registered.
55+
// Deprecated: NewEmptyInterfaceCodec will not be available in Go Driver 2.0. See
56+
// [EmptyInterfaceCodec] for more details.
4357
func NewEmptyInterfaceCodec(opts ...*bsonoptions.EmptyInterfaceCodecOptions) *EmptyInterfaceCodec {
4458
interfaceOpt := bsonoptions.MergeEmptyInterfaceCodecOptions(opts...)
4559

‎bson/bsoncodec/map_codec.go

+22-7
Original file line numberDiff line numberDiff line change
@@ -22,25 +22,40 @@ var defaultMapCodec = NewMapCodec()
2222

2323
// MapCodec is the Codec used for map values.
2424
//
25-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
26-
// MapCodec registered.
25+
// Deprecated: MapCodec will not be directly configurable in Go Driver 2.0. To
26+
// configure the map encode and decode behavior, use the configuration methods
27+
// on a [go.mongodb.org/mongo-driver/bson.Encoder] or
28+
// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the map encode and
29+
// decode behavior for a mongo.Client, use
30+
// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
31+
//
32+
// For example, to configure a mongo.Client to marshal nil Go maps as empty BSON
33+
// documents, use:
34+
//
35+
// opt := options.Client().SetBSONOptions(&options.BSONOptions{
36+
// NilMapAsEmpty: true,
37+
// })
38+
//
39+
// See the deprecation notice for each field in MapCodec for the corresponding
40+
// settings.
2741
type MapCodec struct {
2842
// DecodeZerosMap causes DecodeValue to delete any existing values from Go maps in the destination
2943
// value passed to Decode before unmarshaling BSON documents into them.
3044
//
31-
// Deprecated: Use bson.Decoder.ZeroMaps instead.
45+
// Deprecated: Use bson.Decoder.ZeroMaps or options.BSONOptions.ZeroMaps instead.
3246
DecodeZerosMap bool
3347

3448
// EncodeNilAsEmpty causes EncodeValue to marshal nil Go maps as empty BSON documents instead of
3549
// BSON null.
3650
//
37-
// Deprecated: Use bson.Encoder.NilMapAsEmpty instead.
51+
// Deprecated: Use bson.Encoder.NilMapAsEmpty or options.BSONOptions.NilMapAsEmpty instead.
3852
EncodeNilAsEmpty bool
3953

4054
// EncodeKeysWithStringer causes the Encoder to convert Go map keys to BSON document field name
4155
// strings using fmt.Sprintf() instead of the default string conversion logic.
4256
//
43-
// Deprecated: Use bson.Encoder.StringifyMapKeysWithFmt instead.
57+
// Deprecated: Use bson.Encoder.StringifyMapKeysWithFmt or
58+
// options.BSONOptions.StringifyMapKeysWithFmt instead.
4459
EncodeKeysWithStringer bool
4560
}
4661

@@ -62,8 +77,8 @@ type KeyUnmarshaler interface {
6277

6378
// NewMapCodec returns a MapCodec with options opts.
6479
//
65-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
66-
// MapCodec registered.
80+
// Deprecated: NewMapCodec will not be available in Go Driver 2.0. See
81+
// [MapCodec] for more details.
6782
func NewMapCodec(opts ...*bsonoptions.MapCodecOptions) *MapCodec {
6883
mapOpt := bsonoptions.MergeMapCodecOptions(opts...)
6984

‎bson/bsoncodec/pointer_codec.go

+12-4
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,25 @@ var _ ValueDecoder = &PointerCodec{}
1818

1919
// PointerCodec is the Codec used for pointers.
2020
//
21-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
22-
// PointerCodec registered.
21+
// Deprecated: PointerCodec will not be directly accessible in Go Driver 2.0. To
22+
// override the default pointer encode and decode behavior, create a new registry
23+
// with [go.mongodb.org/mongo-driver/bson.NewRegistry] and register a new
24+
// encoder and decoder for pointers.
25+
//
26+
// For example,
27+
//
28+
// reg := bson.NewRegistry()
29+
// reg.RegisterKindEncoder(reflect.Ptr, myPointerEncoder)
30+
// reg.RegisterKindDecoder(reflect.Ptr, myPointerDecoder)
2331
type PointerCodec struct {
2432
ecache typeEncoderCache
2533
dcache typeDecoderCache
2634
}
2735

2836
// NewPointerCodec returns a PointerCodec that has been initialized.
2937
//
30-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
31-
// PointerCodec registered.
38+
// Deprecated: NewPointerCodec will not be available in Go Driver 2.0. See
39+
// [PointerCodec] for more details.
3240
func NewPointerCodec() *PointerCodec {
3341
return &PointerCodec{}
3442
}

‎bson/bsoncodec/slice_codec.go

+18-4
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,22 @@ var defaultSliceCodec = NewSliceCodec()
2121

2222
// SliceCodec is the Codec used for slice values.
2323
//
24-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
25-
// SliceCodec registered.
24+
// Deprecated: SliceCodec will not be directly configurable in Go Driver 2.0. To
25+
// configure the slice encode and decode behavior, use the configuration methods
26+
// on a [go.mongodb.org/mongo-driver/bson.Encoder] or
27+
// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the slice encode and
28+
// decode behavior for a mongo.Client, use
29+
// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
30+
//
31+
// For example, to configure a mongo.Client to marshal nil Go slices as empty
32+
// BSON arrays, use:
33+
//
34+
// opt := options.Client().SetBSONOptions(&options.BSONOptions{
35+
// NilSliceAsEmpty: true,
36+
// })
37+
//
38+
// See the deprecation notice for each field in SliceCodec for the corresponding
39+
// settings.
2640
type SliceCodec struct {
2741
// EncodeNilAsEmpty causes EncodeValue to marshal nil Go slices as empty BSON arrays instead of
2842
// BSON null.
@@ -33,8 +47,8 @@ type SliceCodec struct {
3347

3448
// NewSliceCodec returns a MapCodec with options opts.
3549
//
36-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
37-
// SliceCodec registered.
50+
// Deprecated: NewSliceCodec will not be available in Go Driver 2.0. See
51+
// [SliceCodec] for more details.
3852
func NewSliceCodec(opts ...*bsonoptions.SliceCodecOptions) *SliceCodec {
3953
sliceOpt := bsonoptions.MergeSliceCodecOptions(opts...)
4054

‎bson/bsoncodec/string_codec.go

+12-4
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,16 @@ import (
1717

1818
// StringCodec is the Codec used for string values.
1919
//
20-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
21-
// StringCodec registered.
20+
// Deprecated: StringCodec will not be directly accessible in Go Driver 2.0. To
21+
// override the default string encode and decode behavior, create a new registry
22+
// with [go.mongodb.org/mongo-driver/bson.NewRegistry] and register a new
23+
// encoder and decoder for strings.
24+
//
25+
// For example,
26+
//
27+
// reg := bson.NewRegistry()
28+
// reg.RegisterKindEncoder(reflect.String, myStringEncoder)
29+
// reg.RegisterKindDecoder(reflect.String, myStringDecoder)
2230
type StringCodec struct {
2331
// DecodeObjectIDAsHex specifies if object IDs should be decoded as their hex representation.
2432
// If false, a string made from the raw object ID bytes will be used. Defaults to true.
@@ -38,8 +46,8 @@ var (
3846

3947
// NewStringCodec returns a StringCodec with options opts.
4048
//
41-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
42-
// StringCodec registered.
49+
// Deprecated: NewStringCodec will not be available in Go Driver 2.0. See
50+
// [StringCodec] for more details.
4351
func NewStringCodec(opts ...*bsonoptions.StringCodecOptions) *StringCodec {
4452
stringOpt := bsonoptions.MergeStringCodecOptions(opts...)
4553
return &StringCodec{*stringOpt.DecodeObjectIDAsHex}

‎bson/bsoncodec/struct_codec.go

+22-7
Original file line numberDiff line numberDiff line change
@@ -60,16 +60,30 @@ type Zeroer interface {
6060

6161
// StructCodec is the Codec used for struct values.
6262
//
63-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
64-
// StructCodec registered.
63+
// Deprecated: StructCodec will not be directly configurable in Go Driver 2.0.
64+
// To configure the struct encode and decode behavior, use the configuration
65+
// methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
66+
// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the struct encode
67+
// and decode behavior for a mongo.Client, use
68+
// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
69+
//
70+
// For example, to configure a mongo.Client to omit zero-value structs when
71+
// using the "omitempty" struct tag, use:
72+
//
73+
// opt := options.Client().SetBSONOptions(&options.BSONOptions{
74+
// OmitZeroStruct: true,
75+
// })
76+
//
77+
// See the deprecation notice for each field in StructCodec for the corresponding
78+
// settings.
6579
type StructCodec struct {
6680
cache sync.Map // map[reflect.Type]*structDescription
6781
parser StructTagParser
6882

6983
// DecodeZeroStruct causes DecodeValue to delete any existing values from Go structs in the
7084
// destination value passed to Decode before unmarshaling BSON documents into them.
7185
//
72-
// Deprecated: Use bson.Decoder.ZeroStructs instead.
86+
// Deprecated: Use bson.Decoder.ZeroStructs or options.BSONOptions.ZeroStructs instead.
7387
DecodeZeroStruct bool
7488

7589
// DecodeDeepZeroInline causes DecodeValue to delete any existing values from Go structs in the
@@ -82,7 +96,7 @@ type StructCodec struct {
8296
// MyStruct{}) as empty and omit it from the marshaled BSON when the "omitempty" struct tag
8397
// option is set.
8498
//
85-
// Deprecated: Use bson.Encoder.OmitZeroStruct instead.
99+
// Deprecated: Use bson.Encoder.OmitZeroStruct or options.BSONOptions.OmitZeroStruct instead.
86100
EncodeOmitDefaultStruct bool
87101

88102
// AllowUnexportedFields allows encoding and decoding values from un-exported struct fields.
@@ -95,7 +109,8 @@ type StructCodec struct {
95109
// a duplicate field in the marshaled BSON when the "inline" struct tag option is set. The
96110
// default value is true.
97111
//
98-
// Deprecated: Use bson.Encoder.ErrorOnInlineDuplicates instead.
112+
// Deprecated: Use bson.Encoder.ErrorOnInlineDuplicates or
113+
// options.BSONOptions.ErrorOnInlineDuplicates instead.
99114
OverwriteDuplicatedInlinedFields bool
100115
}
101116

@@ -104,8 +119,8 @@ var _ ValueDecoder = &StructCodec{}
104119

105120
// NewStructCodec returns a StructCodec that uses p for struct tag parsing.
106121
//
107-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
108-
// StructCodec registered.
122+
// Deprecated: NewStructCodec will not be available in Go Driver 2.0. See
123+
// [StructCodec] for more details.
109124
func NewStructCodec(p StructTagParser, opts ...*bsonoptions.StructCodecOptions) (*StructCodec, error) {
110125
if p == nil {
111126
return nil, errors.New("a StructTagParser must be provided to NewStructCodec")

‎bson/bsoncodec/time_codec.go

+19-5
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,26 @@ const (
2323

2424
// TimeCodec is the Codec used for time.Time values.
2525
//
26-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
27-
// TimeCodec registered.
26+
// Deprecated: TimeCodec will not be directly configurable in Go Driver 2.0.
27+
// To configure the time.Time encode and decode behavior, use the configuration
28+
// methods on a [go.mongodb.org/mongo-driver/bson.Encoder] or
29+
// [go.mongodb.org/mongo-driver/bson.Decoder]. To configure the time.Time encode
30+
// and decode behavior for a mongo.Client, use
31+
// [go.mongodb.org/mongo-driver/mongo/options.ClientOptions.SetBSONOptions].
32+
//
33+
// For example, to configure a mongo.Client to ..., use:
34+
//
35+
// opt := options.Client().SetBSONOptions(&options.BSONOptions{
36+
// UseLocalTimeZone: true,
37+
// })
38+
//
39+
// See the deprecation notice for each field in TimeCodec for the corresponding
40+
// settings.
2841
type TimeCodec struct {
2942
// UseLocalTimeZone specifies if we should decode into the local time zone. Defaults to false.
3043
//
31-
// Deprecated: Use bson.Decoder.UseLocalTimeZone instead.
44+
// Deprecated: Use bson.Decoder.UseLocalTimeZone or options.BSONOptions.UseLocalTimeZone
45+
// instead.
3246
UseLocalTimeZone bool
3347
}
3448

@@ -42,8 +56,8 @@ var (
4256

4357
// NewTimeCodec returns a TimeCodec with options opts.
4458
//
45-
// Deprecated: Use [go.mongodb.org/mongo-driver/bson.NewRegistry] to get a registry with the
46-
// TimeCodec registered.
59+
// Deprecated: NewTimeCodec will not be available in Go Driver 2.0. See
60+
// [TimeCodec] for more details.
4761
func NewTimeCodec(opts ...*bsonoptions.TimeCodecOptions) *TimeCodec {
4862
timeOpt := bsonoptions.MergeTimeCodecOptions(opts...)
4963

0 commit comments

Comments
 (0)