GODRIVER-1736 Fix deprecation notice formats

bson/bsoncodec/default_value_decoders.go

@@ -341,8 +341,8 @@ func (dvd DefaultValueDecoders) IntDecodeValue(dc DecodeContext, vr bsonrw.Value
 }
 
 // UintDecodeValue is the ValueDecoderFunc for uint types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use UIntCodec.DecodeValue instead.
+//
+// Deprecated: UintDecodeValue is not registered by default. Use UintCodec.DecodeValue instead.
 func (dvd DefaultValueDecoders) UintDecodeValue(dc DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
 	var i64 int64
 	var err error
@@ -502,8 +502,8 @@ func (dvd DefaultValueDecoders) FloatDecodeValue(ec DecodeContext, vr bsonrw.Val
 }
 
 // StringDecodeValue is the ValueDecoderFunc for string types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use StringCodec.DecodeValue instead.
+//
+// Deprecated: StringDecodeValue is not registered by default. Use StringCodec.DecodeValue instead.
 func (dvd DefaultValueDecoders) StringDecodeValue(dctx DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
 	var str string
 	var err error
@@ -1213,8 +1213,8 @@ func (dvd DefaultValueDecoders) URLDecodeValue(dc DecodeContext, vr bsonrw.Value
 }
 
 // TimeDecodeValue is the ValueDecoderFunc for time.Time.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use Time.DecodeValue instead.
+//
+// Deprecated: TimeDecodeValue is not registered by default. Use TimeCodec.DecodeValue instead.
 func (dvd DefaultValueDecoders) TimeDecodeValue(dc DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
 	if vr.Type() != bsontype.DateTime {
 		return fmt.Errorf("cannot decode %v into a time.Time", vr.Type())
@@ -1234,8 +1234,8 @@ func (dvd DefaultValueDecoders) TimeDecodeValue(dc DecodeContext, vr bsonrw.Valu
 }
 
 // ByteSliceDecodeValue is the ValueDecoderFunc for []byte.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use ByteSliceCodec.DecodeValue instead.
+//
+// Deprecated: ByteSliceDecodeValue is not registered by default. Use ByteSliceCodec.DecodeValue instead.
 func (dvd DefaultValueDecoders) ByteSliceDecodeValue(dc DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
 	if vr.Type() != bsontype.Binary && vr.Type() != bsontype.Null {
 		return fmt.Errorf("cannot decode %v into a []byte", vr.Type())
@@ -1263,8 +1263,8 @@ func (dvd DefaultValueDecoders) ByteSliceDecodeValue(dc DecodeContext, vr bsonrw
 }
 
 // MapDecodeValue is the ValueDecoderFunc for map[string]* types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use Map.DecodeValue instead.
+//
+// Deprecated: MapDecodeValue is not registered by default. Use MapCodec.DecodeValue instead.
 func (dvd DefaultValueDecoders) MapDecodeValue(dc DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
 	if !val.CanSet() || val.Kind() != reflect.Map || val.Type().Key().Kind() != reflect.String {
 		return ValueDecoderError{Name: "MapDecodeValue", Kinds: []reflect.Kind{reflect.Map}, Received: val}
@@ -1387,8 +1387,8 @@ func (dvd DefaultValueDecoders) ArrayDecodeValue(dc DecodeContext, vr bsonrw.Val
 }
 
 // SliceDecodeValue is the ValueDecoderFunc for slice types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use SliceCodec.DecodeValue instead.
+//
+// Deprecated: SliceDecodeValue is not registered by default. Use SliceCodec.DecodeValue instead.
 func (dvd DefaultValueDecoders) SliceDecodeValue(dc DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
 	if !val.CanSet() || val.Kind() != reflect.Slice {
 		return ValueDecoderError{Name: "SliceDecodeValue", Kinds: []reflect.Kind{reflect.Slice}, Received: val}
@@ -1498,8 +1498,8 @@ func (dvd DefaultValueDecoders) UnmarshalerDecodeValue(dc DecodeContext, vr bson
 }
 
 // EmptyInterfaceDecodeValue is the ValueDecoderFunc for interface{}.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use EmptyInterfaceCodec.DecodeValue instead.
+//
+// Deprecated: EmptyInterfaceDecodeValue is not registered by default. Use EmptyInterfaceCodec.DecodeValue instead.
 func (dvd DefaultValueDecoders) EmptyInterfaceDecodeValue(dc DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
 	if !val.CanSet() || val.Type() != tEmpty {
 		return ValueDecoderError{Name: "EmptyInterfaceDecodeValue", Types: []reflect.Type{tEmpty}, Received: val}

bson/bsoncodec/default_value_encoders.go

@@ -150,8 +150,8 @@ func (dve DefaultValueEncoders) IntEncodeValue(ec EncodeContext, vw bsonrw.Value
 }
 
 // UintEncodeValue is the ValueEncoderFunc for uint types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use UIntCodec.EncodeValue instead.
+//
+// Deprecated: UintEncodeValue is not registered by default. Use UintCodec.EncodeValue instead.
 func (dve DefaultValueEncoders) UintEncodeValue(ec EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
 	switch val.Kind() {
 	case reflect.Uint8, reflect.Uint16:
@@ -185,8 +185,8 @@ func (dve DefaultValueEncoders) FloatEncodeValue(ec EncodeContext, vw bsonrw.Val
 }
 
 // StringEncodeValue is the ValueEncoderFunc for string types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use StringCodec.EncodeValue instead.
+//
+// Deprecated: StringEncodeValue is not registered by default. Use StringCodec.EncodeValue instead.
 func (dve DefaultValueEncoders) StringEncodeValue(ectx EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
 	if val.Kind() != reflect.String {
 		return ValueEncoderError{
@@ -245,8 +245,8 @@ func (dve DefaultValueEncoders) URLEncodeValue(ec EncodeContext, vw bsonrw.Value
 }
 
 // TimeEncodeValue is the ValueEncoderFunc for time.TIme.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use TimeCodec.EncodeValue instead.
+//
+// Deprecated: TimeEncodeValue is not registered by default. Use TimeCodec.EncodeValue instead.
 func (dve DefaultValueEncoders) TimeEncodeValue(ec EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
 	if !val.IsValid() || val.Type() != tTime {
 		return ValueEncoderError{Name: "TimeEncodeValue", Types: []reflect.Type{tTime}, Received: val}
@@ -257,8 +257,8 @@ func (dve DefaultValueEncoders) TimeEncodeValue(ec EncodeContext, vw bsonrw.Valu
 }
 
 // ByteSliceEncodeValue is the ValueEncoderFunc for []byte.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use ByteSliceCodec.EncodeValue instead.
+//
+// Deprecated: ByteSliceEncodeValue is not registered by default. Use ByteSliceCodec.EncodeValue instead.
 func (dve DefaultValueEncoders) ByteSliceEncodeValue(ec EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
 	if !val.IsValid() || val.Type() != tByteSlice {
 		return ValueEncoderError{Name: "ByteSliceEncodeValue", Types: []reflect.Type{tByteSlice}, Received: val}
@@ -270,8 +270,8 @@ func (dve DefaultValueEncoders) ByteSliceEncodeValue(ec EncodeContext, vw bsonrw
 }
 
 // MapEncodeValue is the ValueEncoderFunc for map[string]* types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use MapCodec.EncodeValue instead.
+//
+// Deprecated: MapEncodeValue is not registered by default. Use MapCodec.EncodeValue instead.
 func (dve DefaultValueEncoders) MapEncodeValue(ec EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
 	if !val.IsValid() || val.Kind() != reflect.Map || val.Type().Key().Kind() != reflect.String {
 		return ValueEncoderError{Name: "MapEncodeValue", Kinds: []reflect.Kind{reflect.Map}, Received: val}
@@ -420,8 +420,8 @@ func (dve DefaultValueEncoders) ArrayEncodeValue(ec EncodeContext, vw bsonrw.Val
 }
 
 // SliceEncodeValue is the ValueEncoderFunc for slice types.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use SliceCodec.EncodeValue instead.
+//
+// Deprecated: SliceEncodeValue is not registered by default. Use SliceCodec.EncodeValue instead.
 func (dve DefaultValueEncoders) SliceEncodeValue(ec EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
 	if !val.IsValid() || val.Kind() != reflect.Slice {
 		return ValueEncoderError{Name: "SliceEncodeValue", Kinds: []reflect.Kind{reflect.Slice}, Received: val}
@@ -502,8 +502,8 @@ func (dve DefaultValueEncoders) lookupElementEncoder(ec EncodeContext, origEncod
 }
 
 // EmptyInterfaceEncodeValue is the ValueEncoderFunc for interface{}.
-// This method is deprecated and does not have any stability guarantees. It may be removed in the
-// future. Use EmptyInterfaceCodec.EncodeValue instead.
+//
+// Deprecated: EmptyInterfaceEncodeValue is not registered by default. Use EmptyInterfaceCodec.EncodeValue instead.
 func (dve DefaultValueEncoders) EmptyInterfaceEncodeValue(ec EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
 	if !val.IsValid() || val.Type() != tEmpty {
 		return ValueEncoderError{Name: "EmptyInterfaceEncodeValue", Types: []reflect.Type{tEmpty}, Received: val}

mongo/cursor.go

@@ -269,8 +269,11 @@ func (c *Cursor) closeImplicitSession() {
 }
 
 // BatchCursorFromCursor returns a driver.BatchCursor for the given Cursor. If there is no underlying
-// driver.BatchCursor, nil is returned. This method is deprecated and does not have any stability guarantees. It may be
-// removed in the future.
+// driver.BatchCursor, nil is returned.
+//
+// Deprecated: This is an unstable function because the driver.BatchCursor type exists in the "x" package. Both this
+// function and the driver.BatchCursor type should not be used by applications and may be changed or removed in any
+// release.
 func BatchCursorFromCursor(c *Cursor) *driver.BatchCursor {
 	bc, _ := c.bc.(*driver.BatchCursor)
 	return bc

mongo/index_options_builder.go

@@ -10,125 +10,167 @@ import (
 	"go.mongodb.org/mongo-driver/bson"
 )
 
-// IndexOptionsBuilder is deprecated and unused.  Use mongo/options.IndexOptions instead.
+// IndexOptionsBuilder specifies options for a new index.
+//
+// Deprecated: Use the IndexOptions type in the mongo/options package instead.
 type IndexOptionsBuilder struct {
 	document bson.D
 }
 
-// NewIndexOptionsBuilder is deprecated.
+// NewIndexOptionsBuilder creates a new IndexOptionsBuilder.
+//
+// Deprecated: Use the Index function in mongo/options instead.
 func NewIndexOptionsBuilder() *IndexOptionsBuilder {
 	return &IndexOptionsBuilder{}
 }
 
-// Background is deprecated.
+// Background specifies a value for the background option.
+//
+// Deprecated: Use the IndexOptions.SetBackground function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Background(background bool) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"background", background})
 	return iob
 }
 
-// ExpireAfterSeconds is deprecated.
+// ExpireAfterSeconds specifies a value for the expireAfterSeconds option.
+//
+// Deprecated: Use the IndexOptions.SetExpireAfterSeconds function in mongo/options instead.
 func (iob *IndexOptionsBuilder) ExpireAfterSeconds(expireAfterSeconds int32) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"expireAfterSeconds", expireAfterSeconds})
 	return iob
 }
 
-// Name is deprecated.
+// Name spcifies a value for the name option.
+//
+// Deprecated: Use the IndexOptions.SetName function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Name(name string) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"name", name})
 	return iob
 }
 
-// Sparse is deprecated.
+// Sparse spcifies a value for the sparse option.
+//
+// Deprecated: Use the IndexOptions.SetSparse function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Sparse(sparse bool) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"sparse", sparse})
 	return iob
 }
 
-// StorageEngine is deprecated.
+// StorageEngine spcifies a value for the storageEngine option.
+//
+// Deprecated: Use the IndexOptions.SetStorageEngine function in mongo/options instead.
 func (iob *IndexOptionsBuilder) StorageEngine(storageEngine interface{}) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"storageEngine", storageEngine})
 	return iob
 }
 
-// Unique is deprecated.
+// Unique spcifies a value for the unique option.
+//
+// Deprecated: Use the IndexOptions.SetUnique function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Unique(unique bool) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"unique", unique})
 	return iob
 }
 
-// Version is deprecated.
+// Version spcifies a value for the version option.
+//
+// Deprecated: Use the IndexOptions.SetVersion function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Version(version int32) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"v", version})
 	return iob
 }
 
-// DefaultLanguage is deprecated.
+// DefaultLanguage spcifies a value for the default_language option.
+//
+// Deprecated: Use the IndexOptions.SetDefaultLanguage function in mongo/options instead.
 func (iob *IndexOptionsBuilder) DefaultLanguage(defaultLanguage string) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"default_language", defaultLanguage})
 	return iob
 }
 
-// LanguageOverride is deprecated.
+// LanguageOverride spcifies a value for the language_override option.
+//
+// Deprecated: Use the IndexOptions.SetLanguageOverride function in mongo/options instead.
 func (iob *IndexOptionsBuilder) LanguageOverride(languageOverride string) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"language_override", languageOverride})
 	return iob
 }
 
-// TextVersion is deprecated.
+// TextVersion spcifies a value for the textIndexVersion option.
+//
+// Deprecated: Use the IndexOptions.SetTextVersion function in mongo/options instead.
 func (iob *IndexOptionsBuilder) TextVersion(textVersion int32) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"textIndexVersion", textVersion})
 	return iob
 }
 
-// Weights is deprecated.
+// Weights spcifies a value for the weights option.
+//
+// Deprecated: Use the IndexOptions.SetWeights function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Weights(weights interface{}) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"weights", weights})
 	return iob
 }
 
-// SphereVersion is deprecated.
+// SphereVersion spcifies a value for the 2dsphereIndexVersion option.
+//
+// Deprecated: Use the IndexOptions.SetSphereVersion function in mongo/options instead.
 func (iob *IndexOptionsBuilder) SphereVersion(sphereVersion int32) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"2dsphereIndexVersion", sphereVersion})
 	return iob
 }
 
-// Bits is deprecated.
+// Bits spcifies a value for the bits option.
+//
+// Deprecated: Use the IndexOptions.SetBits function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Bits(bits int32) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"bits", bits})
 	return iob
 }
 
-// Max is deprecated.
+// Max spcifies a value for the max option.
+//
+// Deprecated: Use the IndexOptions.SetMax function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Max(max float64) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"max", max})
 	return iob
 }
 
-// Min is deprecated.
+// Min spcifies a value for the min option.
+//
+// Deprecated: Use the IndexOptions.SetMin function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Min(min float64) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"min", min})
 	return iob
 }
 
-// BucketSize is deprecated.
+// BucketSize spcifies a value for the bucketSize option.
+//
+// Deprecated: Use the IndexOptions.SetBucketSize function in mongo/options instead.
 func (iob *IndexOptionsBuilder) BucketSize(bucketSize int32) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"bucketSize", bucketSize})
 	return iob
 }
 
-// PartialFilterExpression is deprecated.
+// PartialFilterExpression spcifies a value for the partialFilterExpression option.
+//
+// Deprecated: Use the IndexOptions.SetPartialFilterExpression function in mongo/options instead.
 func (iob *IndexOptionsBuilder) PartialFilterExpression(partialFilterExpression interface{}) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"partialFilterExpression", partialFilterExpression})
 	return iob
 }
 
-// Collation is deprecated.
+// Collation spcifies a value for the collation option.
+//
+// Deprecated: Use the IndexOptions.SetCollation function in mongo/options instead.
 func (iob *IndexOptionsBuilder) Collation(collation interface{}) *IndexOptionsBuilder {
 	iob.document = append(iob.document, bson.E{"collation", collation})
 	return iob
 }
 
-// Build is deprecated.
+// Build finishes constructing an the builder.
+//
+// Deprecated: Use the IndexOptions type in the mongo/options package instead.
 func (iob *IndexOptionsBuilder) Build() bson.D {
 	return iob.document
 }

mongo/session.go

@@ -129,8 +129,10 @@ type Session interface {
 	session()
 }
 
-// XSession is an unstable interface for internal use only. This interface is deprecated and is not part of the
-// stability guarantee. It may be removed at any time.
+// XSession is an unstable interface for internal use only.
+//
+// Deprecated: This interface is unstable because it provides access to a session.Client object, which exists in the
+// "x" package. It should not be used by applications and may be changed or removed in any release.
 type XSession interface {
 	ClientSession() *session.Client
 }