docs improvements

Author: Divjot Arora

bson/bsoncodec/bsoncodec.go

@@ -160,21 +160,19 @@ func (fn ValueDecoderFunc) DecodeValue(dc DecodeContext, vr bsonrw.ValueReader,
 	return fn(dc, vr, val)
 }
 
-// typeDecoder is the interface implemented by types that can handle the decoding of a value by
+// typeDecoder is the interface implemented by types that can handle the decoding of a value given its type.
 type typeDecoder interface {
 	decodeType(DecodeContext, bsonrw.ValueReader, reflect.Type) (reflect.Value, error)
 }
 
-// typeDecoderFunc is an adapter function that allows a function with the correct signature to be
-// used as a TypeDecoder.
+// typeDecoderFunc is an adapter function that allows a function with the correct signature to be used as a typeDecoder.
 type typeDecoderFunc func(DecodeContext, bsonrw.ValueReader, reflect.Type) (reflect.Value, error)
 
 func (fn typeDecoderFunc) decodeType(dc DecodeContext, vr bsonrw.ValueReader, t reflect.Type) (reflect.Value, error) {
 	return fn(dc, vr, t)
 }
 
-// ValueTypeDecoderFunc is an adapter struct that allows two functions with the correct signature
-// to be used as a ValueTypeDecoder.
+// decodeAdapter allows two functions with the correct signatures to be used as both a ValueDecoder and typeDecoder.
 type decodeAdapter struct {
 	ValueDecoderFunc
 	typeDecoderFunc
@@ -183,8 +181,8 @@ type decodeAdapter struct {
 var _ ValueDecoder = decodeAdapter{}
 var _ typeDecoder = decodeAdapter{}
 
-// decodeTypeOrValue calls decoder.decodeType is decoder is a typeDecoder. Otherwise, it allocates a new element of
-// type t and calls decoder.DecodeValue on it.
+// decodeTypeOrValue calls decoder.decodeType is decoder is a typeDecoder. Otherwise, it allocates a new element of type
+// t and calls decoder.DecodeValue on it.
 func decodeTypeOrValue(decoder ValueDecoder, dc DecodeContext, vr bsonrw.ValueReader, t reflect.Type) (reflect.Value, error) {
 	if typeDecoder, ok := decoder.(typeDecoder); ok {
 		return typeDecoder.decodeType(dc, vr, t)

bson/bsoncodec/default_value_decoders.go

@@ -132,6 +132,7 @@ func (dvd DefaultValueDecoders) DDecodeValue(dc DecodeContext, vr bsonrw.ValueRe
 	}
 	typeDecoder, isTypeDecoder := decoder.(typeDecoder)
 
+	// Use the elements in the provided value if it's non nil. Otherwise, allocate a new D instance.
 	var elems primitive.D
 	if !val.IsNil() {
 		val.SetLen(0)
@@ -149,7 +150,9 @@ func (dvd DefaultValueDecoders) DDecodeValue(dc DecodeContext, vr bsonrw.ValueRe
 		}
 
 		// Delegate out to the typeDecoder for interface{} if it exists. If not, create a new interface{} value and
-		// delegate out to the ValueDecoder.
+		// delegate out to the ValueDecoder. This could be accomplished by calling decodeTypeOrValue, but this would
+		// require casting decoder to typeDecoder for every element. Because decoder isn't changing, we can optimize and
+		// only cast once.
 		var elem reflect.Value
 		if isTypeDecoder {
 			elem, err = typeDecoder.decodeType(dc, elemVr, tEmpty)