GODRIVER-3420 Clarify docs and comments. (#1897)

Author: qingyang-hu

bson/decoder.go

@@ -87,7 +87,7 @@ func (d *Decoder) SetRegistry(r *Registry) {
 	d.dc.Registry = r
 }
 
-// DefaultDocumentM causes the Decoder to always unmarshal documents into the primitive.M type. This
+// DefaultDocumentM causes the Decoder to always unmarshal documents into the bson.M type. This
 // behavior is restricted to data typed as "interface{}" or "map[string]interface{}".
 func (d *Decoder) DefaultDocumentM() {
 	d.dc.defaultDocumentType = reflect.TypeOf(M{})
@@ -101,7 +101,7 @@ func (d *Decoder) AllowTruncatingDoubles() {
 }
 
 // BinaryAsSlice causes the Decoder 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.
+// "Old" BSON binary subtype as a Go byte slice instead of a bson.Binary.
 func (d *Decoder) BinaryAsSlice() {
 	d.dc.binaryAsSlice = true
 }

bson/doc.go

@@ -47,20 +47,20 @@
 //  5. BSON boolean unmarshals to a bool.
 //  6. BSON embedded document unmarshals to the parent type (i.e. D for a D, M for an M).
 //  7. BSON array unmarshals to a bson.A.
-//  8. BSON ObjectId unmarshals to a primitive.ObjectID.
-//  9. BSON datetime unmarshals to a primitive.DateTime.
-//  10. BSON binary unmarshals to a primitive.Binary.
-//  11. BSON regular expression unmarshals to a primitive.Regex.
-//  12. BSON JavaScript unmarshals to a primitive.JavaScript.
-//  13. BSON code with scope unmarshals to a primitive.CodeWithScope.
-//  14. BSON timestamp unmarshals to an primitive.Timestamp.
-//  15. BSON 128-bit decimal unmarshals to an primitive.Decimal128.
-//  16. BSON min key unmarshals to an primitive.MinKey.
-//  17. BSON max key unmarshals to an primitive.MaxKey.
-//  18. BSON undefined unmarshals to a primitive.Undefined.
+//  8. BSON ObjectId unmarshals to a bson.ObjectID.
+//  9. BSON datetime unmarshals to a bson.DateTime.
+//  10. BSON binary unmarshals to a bson.Binary.
+//  11. BSON regular expression unmarshals to a bson.Regex.
+//  12. BSON JavaScript unmarshals to a bson.JavaScript.
+//  13. BSON code with scope unmarshals to a bson.CodeWithScope.
+//  14. BSON timestamp unmarshals to an bson.Timestamp.
+//  15. BSON 128-bit decimal unmarshals to an bson.Decimal128.
+//  16. BSON min key unmarshals to an bson.MinKey.
+//  17. BSON max key unmarshals to an bson.MaxKey.
+//  18. BSON undefined unmarshals to a bson.Undefined.
 //  19. BSON null unmarshals to nil.
-//  20. BSON DBPointer unmarshals to a primitive.DBPointer.
-//  21. BSON symbol unmarshals to a primitive.Symbol.
+//  20. BSON DBPointer unmarshals to a bson.DBPointer.
+//  21. BSON symbol unmarshals to a bson.Symbol.
 //
 // The above mappings also apply when marshaling a D or M to BSON. Some other useful marshaling mappings are:
 //

bson/primitive.go

@@ -60,7 +60,7 @@ func (d DateTime) MarshalJSON() ([]byte, error) {
 	return d.Time().UTC().MarshalJSON()
 }
 
-// UnmarshalJSON creates a primitive.DateTime from a JSON string.
+// UnmarshalJSON creates a bson.DateTime from a JSON string.
 func (d *DateTime) UnmarshalJSON(data []byte) error {
 	// Ignore "null" so that we can distinguish between a "null" value and
 	// valid value that is the zero time (as reported by time.Time.IsZero).

docs/migration-2.0.md

@@ -867,6 +867,34 @@ The `NewRegistryBuilder` function has been removed along with the `bsoncodec.Reg
 
 ### Decoder
 
+The BSON decoding logic has changed to decode into a `bson.D` by default.
+
+The example shows the behavior change.
+
+```go
+// v1
+
+b1 := bson.M{"a": 1, "b": bson.M{"c": 2}}
+b2, _ := bson.Marshal(b1)
+b3 := bson.M{}
+bson.Unmarshal(b2, &b3)
+fmt.Printf("b3.b type: %T\n", b3["b"])
+// Output: b3.b type: primitive.M
+```
+
+```go
+// v2
+
+b1 := bson.M{"a": 1, "b": bson.M{"c": 2}}
+b2, _ := bson.Marshal(b1)
+b3 := bson.M{}
+bson.Unmarshal(b2, &b3)
+fmt.Printf("b3.b type: %T\n", b3["b"])
+// Output: b3.b type: bson.D
+```
+
+Use `Decoder.DefaultDocumentM()` or set the `DefaultDocumentM` field of `options.BSONOptions` to always decode documents into the `bson.M` type.
+
 #### NewDecoder
 
 The signature of `NewDecoder` has been updated without an error being returned.
@@ -1043,11 +1071,11 @@ The signature of `Reset` has been updated without an error being returned.
 
 #### DefaultDocumentD / DefaultDocumentM
 
-`Decoder.DefaultDocumentD` has been removed since a document, including a top-level value (e.g. you pass in an empty interface value to Decode), is always decoded into a `bson.D` by default. Therefore, use `Decoder.DefaultDocumentM` to always decode a document into a `bson.M` to avoid unexpected decode results.
+`Decoder.DefaultDocumentD()` has been removed since a document, including a top-level value (e.g. you pass in an empty interface value to Decode), is always decoded into a `bson.D` by default. Therefore, use `Decoder.DefaultDocumentM()` to always decode a document into a `bson.M` to avoid unexpected decode results.
 
 #### ObjectIDAsHexString
 
-`Decoder.ObjectIDAsHexString` method enables decoding a BSON ObjectId as a hexadecimal string. Otherwise, the decoder returns an error by default instead of decoding as the UTF-8 representation of the raw ObjectId bytes, which results in a garbled and unusable string.
+`Decoder.ObjectIDAsHexString()` method enables decoding a BSON ObjectId as a hexadecimal string. Otherwise, the decoder returns an error by default instead of decoding as the UTF-8 representation of the raw ObjectId bytes, which results in a garbled and unusable string.
 
 ### Encoder
 

mongo/gridfs_download_stream.go

@@ -52,7 +52,7 @@ type GridFSDownloadStream struct {
 // GridFSDownloadStream.GetFile method.
 type GridFSFile struct {
 	// ID is the file's ID. This will match the file ID specified when uploading the file. If an upload helper that
-	// does not require a file ID was used, this field will be a primitive.ObjectID.
+	// does not require a file ID was used, this field will be a bson.ObjectID.
 	ID interface{}
 
 	// Length is the length of this file in bytes.

mongo/options/clientoptions.go

@@ -197,11 +197,11 @@ type BSONOptions struct {
 
 	// BinaryAsSlice causes the driver 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.
+	// instead of a bson.Binary.
 	BinaryAsSlice bool
 
 	// DefaultDocumentM causes the driver to always unmarshal documents into the
-	// primitive.M type. This behavior is restricted to data typed as
+	// bson.M type. This behavior is restricted to data typed as
 	// "interface{}" or "map[string]interface{}".
 	DefaultDocumentM bool
 

mongo/options/encryptoptions.go

@@ -128,7 +128,7 @@ func Encrypt() *EncryptOptionsBuilder {
 	return &EncryptOptionsBuilder{}
 }
 
-// SetKeyID specifies an _id of a data key. This should be a UUID (a primitive.Binary with subtype 4).
+// SetKeyID specifies an _id of a data key. This should be a UUID (a bson.Binary with subtype 4).
 func (e *EncryptOptionsBuilder) SetKeyID(keyID bson.Binary) *EncryptOptionsBuilder {
 	e.Opts = append(e.Opts, func(opts *EncryptOptions) error {
 		opts.KeyID = &keyID