Improve various documentation, add examples for using bson.Raw and bson.RawValue when encoding/decoding BSON. (#1171)

Co-authored-by: Preston Vasquez <[email protected]>

Author: matthewdale

bson/example_test.go

@@ -0,0 +1,137 @@
+package bson_test
+
+import (
+	"fmt"
+	"time"
+
+	"go.mongodb.org/mongo-driver/bson"
+)
+
+// This example uses Raw to skip parsing a nested document in a BSON message.
+func ExampleRaw_unmarshal() {
+	b, err := bson.Marshal(bson.M{
+		"Word":     "beach",
+		"Synonyms": bson.A{"coast", "shore", "waterfront"},
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	var res struct {
+		Word     string
+		Synonyms bson.Raw // Don't parse the whole list, we just want to count the elements.
+	}
+
+	err = bson.Unmarshal(b, &res)
+	if err != nil {
+		panic(err)
+	}
+	elems, err := res.Synonyms.Elements()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("%s, synonyms count: %d\n", res.Word, len(elems))
+
+	// Output: beach, synonyms count: 3
+}
+
+// This example uses Raw to add a precomputed BSON document during marshal.
+func ExampleRaw_marshal() {
+	precomputed, err := bson.Marshal(bson.M{"Precomputed": true})
+	if err != nil {
+		panic(err)
+	}
+
+	msg := struct {
+		Message  string
+		Metadata bson.Raw
+	}{
+		Message:  "Hello World!",
+		Metadata: precomputed,
+	}
+
+	b, err := bson.Marshal(msg)
+	if err != nil {
+		panic(err)
+	}
+	// Print the Extended JSON by converting BSON to bson.Raw.
+	fmt.Println(bson.Raw(b).String())
+
+	// Output: {"message": "Hello World!","metadata": {"Precomputed": true}}
+}
+
+// This example uses RawValue to delay parsing a value in a BSON message.
+func ExampleRawValue_unmarshal() {
+	b1, err := bson.Marshal(bson.M{
+		"Format":    "UNIX",
+		"Timestamp": 1675282389,
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	b2, err := bson.Marshal(bson.M{
+		"Format":    "RFC3339",
+		"Timestamp": time.Unix(1675282389, 0).Format(time.RFC3339),
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	for _, b := range [][]byte{b1, b2} {
+		var res struct {
+			Format    string
+			Timestamp bson.RawValue // Delay parsing until we know the timestamp format.
+		}
+
+		err = bson.Unmarshal(b, &res)
+		if err != nil {
+			panic(err)
+		}
+
+		var t time.Time
+		switch res.Format {
+		case "UNIX":
+			t = time.Unix(res.Timestamp.AsInt64(), 0)
+		case "RFC3339":
+			t, err = time.Parse(time.RFC3339, res.Timestamp.StringValue())
+			if err != nil {
+				panic(err)
+			}
+		}
+		fmt.Println(res.Format, t.Unix())
+	}
+
+	// Output:
+	// UNIX 1675282389
+	// RFC3339 1675282389
+}
+
+// This example uses RawValue to add a precomputed BSON string value during marshal.
+func ExampleRawValue_marshal() {
+	t, val, err := bson.MarshalValue("Precomputed message!")
+	if err != nil {
+		panic(err)
+	}
+	precomputed := bson.RawValue{
+		Type:  t,
+		Value: val,
+	}
+
+	msg := struct {
+		Message bson.RawValue
+		Time    time.Time
+	}{
+		Message: precomputed,
+		Time:    time.Unix(1675282389, 0),
+	}
+
+	b, err := bson.Marshal(msg)
+	if err != nil {
+		panic(err)
+	}
+	// Print the Extended JSON by converting BSON to bson.Raw.
+	fmt.Println(bson.Raw(b).String())
+
+	// Output: {"message": "Precomputed message!","time": {"$date":{"$numberLong":"1675282389000"}}}
+}

bson/marshal.go

@@ -20,17 +20,23 @@ const defaultDstCap = 256
 var bvwPool = bsonrw.NewBSONValueWriterPool()
 var extjPool = bsonrw.NewExtJSONValueWriterPool()
 
-// Marshaler is an interface implemented by types that can marshal themselves
-// into a BSON document represented as bytes. The bytes returned must be a valid
-// BSON document if the error is nil.
+// Marshaler is the interface implemented by types that can marshal themselves
+// into a valid BSON document.
+//
+// Implementations of Marshaler must return a full BSON document. To create
+// custom BSON marshaling behavior for individual values in a BSON document,
+// implement the ValueMarshaler interface instead.
 type Marshaler interface {
 	MarshalBSON() ([]byte, error)
 }
 
-// ValueMarshaler is an interface implemented by types that can marshal
-// themselves into a BSON value as bytes. The type must be the valid type for
-// the bytes returned. The bytes and byte type together must be valid if the
-// error is nil.
+// ValueMarshaler is the interface implemented by types that can marshal
+// themselves into a valid BSON value. The format of the returned bytes must
+// match the returned type.
+//
+// Implementations of ValueMarshaler must return an individual BSON value. To
+// create custom BSON marshaling behavior for an entire BSON document, implement
+// the Marshaler interface instead.
 type ValueMarshaler interface {
 	MarshalBSONValue() (bsontype.Type, []byte, error)
 }

bson/raw.go

@@ -16,9 +16,10 @@ import (
 // ErrNilReader indicates that an operation was attempted on a nil bson.Reader.
 var ErrNilReader = errors.New("nil reader")
 
-// Raw is a wrapper around a byte slice. It will interpret the slice as a
-// BSON document. This type is a wrapper around a bsoncore.Document. Errors returned from the
-// methods on this type and associated types come from the bsoncore package.
+// Raw is a raw encoded BSON document. It can be used to delay BSON document decoding or precompute
+// a BSON encoded document.
+//
+// A Raw must be a full BSON document. Use the RawValue type for individual BSON values.
 type Raw []byte
 
 // NewFromIOReader reads in a document from the given io.Reader and constructs a Raw from
@@ -81,5 +82,5 @@ func (r Raw) IndexErr(index uint) (RawElement, error) {
 	return RawElement(elem), err
 }
 
-// String implements the fmt.Stringer interface.
+// String returns the BSON document encoded as Extended JSON.
 func (r Raw) String() string { return bsoncore.Document(r).String() }

bson/raw_element.go

@@ -10,10 +10,7 @@ import (
 	"go.mongodb.org/mongo-driver/x/bsonx/bsoncore"
 )
 
-// RawElement represents a BSON element in byte form. This type provides a simple way to
-// transform a slice of bytes into a BSON element and extract information from it.
-//
-// RawElement is a thin wrapper around a bsoncore.Element.
+// RawElement is a raw encoded BSON document or array element.
 type RawElement []byte
 
 // Key returns the key for this element. If the element is not valid, this method returns an empty
@@ -36,7 +33,7 @@ func (re RawElement) ValueErr() (RawValue, error) {
 // Validate ensures re is a valid BSON element.
 func (re RawElement) Validate() error { return bsoncore.Element(re).Validate() }
 
-// String implements the fmt.Stringer interface. The output will be in extended JSON format.
+// String returns the BSON element encoded as Extended JSON.
 func (re RawElement) String() string {
 	doc := bsoncore.BuildDocument(nil, re)
 	j, err := MarshalExtJSON(Raw(doc), true, false)

bson/raw_value.go

@@ -26,11 +26,10 @@ var ErrNilContext = errors.New("DecodeContext cannot be nil")
 // ErrNilRegistry is returned when the provided registry is nil.
 var ErrNilRegistry = errors.New("Registry cannot be nil")
 
-// RawValue represents a BSON value in byte form. It can be used to hold unprocessed BSON or to
-// defer processing of BSON. Type is the BSON type of the value and Value are the raw bytes that
-// represent the element.
+// RawValue is a raw encoded BSON value. It can be used to delay BSON value decoding or precompute
+// BSON encoded value. Type is the BSON type of the value and Value is the raw encoded BSON value.
 //
-// This type wraps bsoncore.Value for most of it's functionality.
+// A RawValue must be an individual BSON value. Use the Raw type for full BSON documents.
 type RawValue struct {
 	Type  bsontype.Type
 	Value []byte

bson/unmarshal.go

@@ -14,18 +14,26 @@ import (
 	"go.mongodb.org/mongo-driver/bson/bsontype"
 )
 
-// Unmarshaler is an interface implemented by types that can unmarshal a BSON
-// document representation of themselves. The BSON bytes can be assumed to be
-// valid. UnmarshalBSON must copy the BSON bytes if it wishes to retain the data
-// after returning.
+// Unmarshaler is the interface implemented by types that can unmarshal a BSON
+// document representation of themselves. The input can be assumed to be a valid
+// encoding of a BSON document. UnmarshalBSON must copy the JSON data if it
+// wishes to retain the data after returning.
+//
+// Unmarshaler is only used to unmarshal full BSON documents. To create custom
+// BSON unmarshaling behavior for individual values in a BSON document,
+// implement the ValueUnmarshaler interface instead.
 type Unmarshaler interface {
 	UnmarshalBSON([]byte) error
 }
 
-// ValueUnmarshaler is an interface implemented by types that can unmarshal a
-// BSON value representation of themselves. The BSON bytes and type can be
-// assumed to be valid. UnmarshalBSONValue must copy the BSON value bytes if it
-// wishes to retain the data after returning.
+// ValueUnmarshaler is the interface implemented by types that can unmarshal a
+// BSON value representation of themselves. The input can be assumed to be a
+// valid encoding of a BSON value. UnmarshalBSONValue must copy the BSON value
+// bytes if it wishes to retain the data after returning.
+//
+// ValueUnmarshaler is only used to unmarshal individual values in a BSON
+// document. To create custom BSON unmarshaling behavior for an entire BSON
+// document, implement the Unmarshaler interface instead.
 type ValueUnmarshaler interface {
 	UnmarshalBSONValue(bsontype.Type, []byte) error
 }

mongo/single_result.go

@@ -111,9 +111,10 @@ func (sr *SingleResult) setRdrContents() error {
 	return ErrNoDocuments
 }
 
-// Err returns the error from the operation that created this SingleResult. If the operation was successful but did not
-// return any documents, Err will return ErrNoDocuments. If the operation was successful and returned a document, Err
-// will return nil.
+// Err provides a way to check for query errors without calling Decode. Err returns the error, if
+// any, that was encountered while running the operation. If the operation was successful but did
+// not return any documents, Err returns ErrNoDocuments. If this error is not nil, this error will
+// also be returned from Decode.
 func (sr *SingleResult) Err() error {
 	sr.err = sr.setRdrContents()