Deprecate direct BSON unmarshaling support for op result types. (#902)

Co-authored-by: Benjamin Rewis <[email protected]>

Author: matthewdale

mongo/results.go

@@ -47,6 +47,8 @@ type InsertManyResult struct {
 	InsertedIDs []interface{}
 }
 
+// TODO(GODRIVER-2367): Remove the BSON struct tags on DeleteResult.
+
 // DeleteResult is the result type returned by DeleteOne and DeleteMany operations.
 type DeleteResult struct {
 	DeletedCount int64 `bson:"n"` // The number of documents deleted.
@@ -91,7 +93,11 @@ type UpdateResult struct {
 }
 
 // UnmarshalBSON implements the bson.Unmarshaler interface.
+//
+// Deprecated: Unmarshalling an UpdateResult directly from BSON is not supported and may produce
+// different results compared to running Update* operations directly.
 func (result *UpdateResult) UnmarshalBSON(b []byte) error {
+	// TODO(GODRIVER-2367): Remove the ability to unmarshal BSON directly to an UpdateResult.
 	elems, err := bson.Raw(b).Elements()
 	if err != nil {
 		return err

mongo/results_test.go

@@ -15,6 +15,7 @@ import (
 
 func TestResults(t *testing.T) {
 	t.Run("delete result", func(t *testing.T) {
+		// TODO(GODRIVER-2367): Do not test the ability to unmarshal BSON directly to a DeleteResult.
 		t.Run("unmarshal into", func(t *testing.T) {
 			doc := bson.D{
 				{"n", int64(2)},
@@ -29,6 +30,7 @@ func TestResults(t *testing.T) {
 			assert.Nil(t, err, "Unmarshal error: %v", err)
 			assert.Equal(t, int64(2), result.DeletedCount, "expected DeletedCount 2, got %v", result.DeletedCount)
 		})
+		// TODO(GODRIVER-2367): Do not test the ability to marshal a DeleteResult to BSON.
 		t.Run("marshal from", func(t *testing.T) {
 			result := DeleteResult{DeletedCount: 1}
 			buf, err := bson.Marshal(result)
@@ -53,6 +55,7 @@ func TestResults(t *testing.T) {
 		})
 	})
 	t.Run("update result", func(t *testing.T) {
+		// TODO(GODRIVER-2367): Do not test the ability to unmarshal BSON directly to an UpdateResult.
 		t.Run("unmarshal into", func(t *testing.T) {
 			doc := bson.D{
 				{"n", 1},