GODRIVER-1329 Document results, errors, and BulkWrite models (#230)

Author: Divjot Arora

mongo/bulk_write_models.go

@@ -10,12 +10,16 @@ import (
 	"go.mongodb.org/mongo-driver/mongo/options"
 )
 
-// WriteModel is the interface satisfied by all models for bulk writes.
+// WriteModel is an interface implemented by models that can be used in a BulkWrite operation. Each WriteModel
+// represents a write.
+//
+// This interface is implemented by InsertOneModel, DeleteOneModel, DeleteManyModel, ReplaceOneModel, UpdateOneModel,
+// and UpdateManyModel. Custom implementations of this interface must not be used.
 type WriteModel interface {
 	writeModel()
 }
 
-// InsertOneModel is the write model for insert operations.
+// InsertOneModel is used to insert a single document in a BulkWrite operation.
 type InsertOneModel struct {
 	Document interface{}
 }
@@ -25,15 +29,17 @@ func NewInsertOneModel() *InsertOneModel {
 	return &InsertOneModel{}
 }
 
-// SetDocument sets the BSON document for the InsertOneModel.
+// SetDocument specifies the document to be inserted. The document cannot be nil. If it does not have an _id field when
+// transformed into BSON, one will be added automatically to the marshalled document. The original document will not be
+// modified.
 func (iom *InsertOneModel) SetDocument(doc interface{}) *InsertOneModel {
 	iom.Document = doc
 	return iom
 }
 
 func (*InsertOneModel) writeModel() {}
 
-// DeleteOneModel is the write model for delete operations.
+// DeleteOneModel is used to delete at most one document in a BulkWriteOperation.
 type DeleteOneModel struct {
 	Filter    interface{}
 	Collation *options.Collation
@@ -44,21 +50,24 @@ func NewDeleteOneModel() *DeleteOneModel {
 	return &DeleteOneModel{}
 }
 
-// SetFilter sets the filter for the DeleteOneModel.
+// SetFilter specifies a filter to use to select the document to delete. The filter must be a document containing query
+// operators. It cannot be nil. If the filter matches multiple documents, one will be selected from the matching
+// documents.
 func (dom *DeleteOneModel) SetFilter(filter interface{}) *DeleteOneModel {
 	dom.Filter = filter
 	return dom
 }
 
-// SetCollation sets the collation for the DeleteOneModel.
+// SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be
+// used.
 func (dom *DeleteOneModel) SetCollation(collation *options.Collation) *DeleteOneModel {
 	dom.Collation = collation
 	return dom
 }
 
 func (*DeleteOneModel) writeModel() {}
 
-// DeleteManyModel is the write model for deleteMany operations.
+// DeleteManyModel is used to delete multiple documents in a BulkWrite operation.
 type DeleteManyModel struct {
 	Filter    interface{}
 	Collation *options.Collation
@@ -69,21 +78,23 @@ func NewDeleteManyModel() *DeleteManyModel {
 	return &DeleteManyModel{}
 }
 
-// SetFilter sets the filter for the DeleteManyModel.
+// SetFilter specifies a filter to use to select documents to delete. The filter must be a document containing query
+// operators. It cannot be nil.
 func (dmm *DeleteManyModel) SetFilter(filter interface{}) *DeleteManyModel {
 	dmm.Filter = filter
 	return dmm
 }
 
-// SetCollation sets the collation for the DeleteManyModel.
+// SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be
+// used.
 func (dmm *DeleteManyModel) SetCollation(collation *options.Collation) *DeleteManyModel {
 	dmm.Collation = collation
 	return dmm
 }
 
 func (*DeleteManyModel) writeModel() {}
 
-// ReplaceOneModel is the write model for replace operations.
+// ReplaceOneModel is used to replace at most one document in a BulkWrite operation.
 type ReplaceOneModel struct {
 	Collation   *options.Collation
 	Upsert      *bool
@@ -96,33 +107,39 @@ func NewReplaceOneModel() *ReplaceOneModel {
 	return &ReplaceOneModel{}
 }
 
-// SetFilter sets the filter for the ReplaceOneModel.
+// SetFilter specifies a filter to use to select the document to replace. The filter must be a document containing query
+// operators. It cannot be nil. If the filter matches multiple documents, one will be selected from the matching
+// documents.
 func (rom *ReplaceOneModel) SetFilter(filter interface{}) *ReplaceOneModel {
 	rom.Filter = filter
 	return rom
 }
 
-// SetReplacement sets the replacement document for the ReplaceOneModel.
+// SetReplacement specifies a document that will be used to replace the selected document. It cannot be nil and cannot
+// contain any update operators (https://docs.mongodb.com/manual/reference/operator/update/).
 func (rom *ReplaceOneModel) SetReplacement(rep interface{}) *ReplaceOneModel {
 	rom.Replacement = rep
 	return rom
 }
 
-// SetCollation sets the collation for the ReplaceOneModel.
+// SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be
+// used.
 func (rom *ReplaceOneModel) SetCollation(collation *options.Collation) *ReplaceOneModel {
 	rom.Collation = collation
 	return rom
 }
 
-// SetUpsert specifies if a new document should be created if no document matches the query.
+// SetUpsert specifies whether or not the replacement document should be inserted if no document matching the filter is
+// found. If an upsert is performed, the _id of the upserted document can be retrieved from the UpsertedIDs field of the
+// BulkWriteResult.
 func (rom *ReplaceOneModel) SetUpsert(upsert bool) *ReplaceOneModel {
 	rom.Upsert = &upsert
 	return rom
 }
 
 func (*ReplaceOneModel) writeModel() {}
 
-// UpdateOneModel is the write model for update operations.
+// UpdateOneModel is used to update at most one document in a BulkWrite operation.
 type UpdateOneModel struct {
 	Collation    *options.Collation
 	Upsert       *bool
@@ -136,39 +153,46 @@ func NewUpdateOneModel() *UpdateOneModel {
 	return &UpdateOneModel{}
 }
 
-// SetFilter sets the filter for the UpdateOneModel.
+// SetFilter specifies a filter to use to select the document to update. The filter must be a document containing query
+// operators. It cannot be nil. If the filter matches multiple documents, one will be selected from the matching
+// documents.
 func (uom *UpdateOneModel) SetFilter(filter interface{}) *UpdateOneModel {
 	uom.Filter = filter
 	return uom
 }
 
-// SetUpdate sets the update document for the UpdateOneModel.
+// SetUpdate specifies the modifications to be made to the selected document. The value must be a document containing
+// update operators (https://docs.mongodb.com/manual/reference/operator/update/). It cannot be nil or empty.
 func (uom *UpdateOneModel) SetUpdate(update interface{}) *UpdateOneModel {
 	uom.Update = update
 	return uom
 }
 
-// SetArrayFilters specifies a set of filters specifying to which array elements an update should apply.
+// SetArrayFilters specifies a set of filters to determine which elements should be modified when updating an array
+// field.
 func (uom *UpdateOneModel) SetArrayFilters(filters options.ArrayFilters) *UpdateOneModel {
 	uom.ArrayFilters = &filters
 	return uom
 }
 
-// SetCollation sets the collation for the UpdateOneModel.
+// SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be
+// used.
 func (uom *UpdateOneModel) SetCollation(collation *options.Collation) *UpdateOneModel {
 	uom.Collation = collation
 	return uom
 }
 
-// SetUpsert specifies if a new document should be created if no document matches the query.
+// SetUpsert specifies whether or not a new document should be inserted if no document matching the filter is found. If
+// an upsert is performed, the _id of the upserted document can be retrieved from the UpsertedIDs field of the
+// BulkWriteResult.
 func (uom *UpdateOneModel) SetUpsert(upsert bool) *UpdateOneModel {
 	uom.Upsert = &upsert
 	return uom
 }
 
 func (*UpdateOneModel) writeModel() {}
 
-// UpdateManyModel is the write model for updateMany operations.
+// UpdateManyModel is used to update multiple documents in a BulkWrite operation.
 type UpdateManyModel struct {
 	Collation    *options.Collation
 	Upsert       *bool
@@ -182,31 +206,37 @@ func NewUpdateManyModel() *UpdateManyModel {
 	return &UpdateManyModel{}
 }
 
-// SetFilter sets the filter for the UpdateManyModel.
+// SetFilter specifies a filter to use to select documents to update. The filter must be a document containing query
+// operators. It cannot be nil.
 func (umm *UpdateManyModel) SetFilter(filter interface{}) *UpdateManyModel {
 	umm.Filter = filter
 	return umm
 }
 
-// SetUpdate sets the update document for the UpdateManyModel.
+// SetUpdate specifies the modifications to be made to the selected documents. The value must be a document containing
+// update operators (https://docs.mongodb.com/manual/reference/operator/update/). It cannot be nil or empty.
 func (umm *UpdateManyModel) SetUpdate(update interface{}) *UpdateManyModel {
 	umm.Update = update
 	return umm
 }
 
-// SetArrayFilters specifies a set of filters specifying to which array elements an update should apply.
+// SetArrayFilters specifies a set of filters to determine which elements should be modified when updating an array
+// field.
 func (umm *UpdateManyModel) SetArrayFilters(filters options.ArrayFilters) *UpdateManyModel {
 	umm.ArrayFilters = &filters
 	return umm
 }
 
-// SetCollation sets the collation for the UpdateManyModel.
+// SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be
+// used.
 func (umm *UpdateManyModel) SetCollation(collation *options.Collation) *UpdateManyModel {
 	umm.Collation = collation
 	return umm
 }
 
-// SetUpsert specifies if a new document should be created if no document matches the query.
+// SetUpsert specifies whether or not a new document should be inserted if no document matching the filter is found. If
+// an upsert is performed, the _id of the upserted document can be retrieved from the UpsertedIDs field of the
+// BulkWriteResult.
 func (umm *UpdateManyModel) SetUpsert(upsert bool) *UpdateManyModel {
 	umm.Upsert = &upsert
 	return umm

mongo/collection.go

@@ -443,7 +443,7 @@ func (coll *Collection) delete(ctx context.Context, filter interface{}, deleteOn
 
 // DeleteOne executes a delete command to delete at most one document from the collection.
 //
-// The filter parameter must be a document containing query parameters and can be used to select the document to be
+// The filter parameter must be a document containing query operators and can be used to select the document to be
 // deleted. It cannot be nil. If the filter does not match any documents, the operation will succeed and a DeleteResult
 // with a DeletedCount of 0 will be returned. If the filter matches multiple documents, one will be selected from the
 // matched set.
@@ -459,7 +459,7 @@ func (coll *Collection) DeleteOne(ctx context.Context, filter interface{},
 
 // DeleteMany executes a delete command to delete documents from the collection.
 //
-// The filter parameter must be a document containing query parameters and can be used to select the documents to
+// The filter parameter must be a document containing query operators and can be used to select the documents to
 // be deleted. It cannot be nil. An empty document (e.g. bson.D{}) should be used to delete all documents in the
 // collection. If the filter does not match any documents, the operation will succeed and a DeleteResult with a
 // DeletedCount of 0 will be returned.