GODRIVER-1377 Database documentation (#215)

Author: Divjot Arora

mongo/database.go

@@ -28,7 +28,7 @@ var (
 	defaultRunCmdOpts = []*options.RunCmdOptions{options.RunCmd().SetReadPreference(readpref.Primary())}
 )
 
-// Database performs operations on a given database.
+// Database is a handle to a MongoDB database. It is safe for concurrent use by multiple goroutines.
 type Database struct {
 	client         *Client
 	name           string
@@ -85,7 +85,7 @@ func newDatabase(client *Client, name string, opts ...*options.DatabaseOptions)
 	return db
 }
 
-// Client returns the Client the database was created from.
+// Client returns the Client the Database was created from.
 func (db *Database) Client() *Client {
 	return db.client
 }
@@ -95,14 +95,21 @@ func (db *Database) Name() string {
 	return db.name
 }
 
-// Collection gets a handle for a given collection in the database.
+// Collection gets a handle for a collection with the given name configured with the given CollectionOptions.
 func (db *Database) Collection(name string, opts ...*options.CollectionOptions) *Collection {
 	return newCollection(db, name, opts...)
 }
 
-// Aggregate runs an aggregation framework pipeline.
+// Aggregate performs an aggregate operation (https://docs.mongodb.com/manual/reference/command/aggregate/) against
+// the database. This requires MongoDB version >= 3.6 and driver version >= 1.1.0.
 //
-// See https://docs.mongodb.com/manual/aggregation/.
+// The pipeline parameter should be a slice of documents, each representing an aggregation stage. The pipeline
+// cannot be nil but can be empty. The stage documents must all be non-nil. For a pipeline of bson.D documents, the
+// mongo.Pipeline type can be used. See
+// https://docs.mongodb.com/manual/reference/operator/aggregation-pipeline/#db-aggregate-stages for a list of valid
+// stages in database-level aggregations.
+//
+// The opts parameter can be used to specify options for this operation (see the options.AggregateOptions documentation).
 func (db *Database) Aggregate(ctx context.Context, pipeline interface{},
 	opts ...*options.AggregateOptions) (*Cursor, error) {
 	a := aggregateParams{
@@ -161,8 +168,13 @@ func (db *Database) processRunCommand(ctx context.Context, cmd interface{},
 		Database(db.name).Deployment(db.client.deployment).ReadConcern(db.readConcern).Crypt(db.client.crypt), sess, nil
 }
 
-// RunCommand runs a command on the database. A user can supply a custom
-// context to this method, or nil to default to context.Background().
+// RunCommand executes the given command against the database.
+//
+// The runCommand parameter should be a document for the command to be executed. It cannot be nil.
+// This must be an order-preserving type such as bson.D. Map types such as bson.M are not valid.
+// If the command document contains a session ID or any transaction-specific fields, the behavior is undefined.
+//
+// The opts parameter can be used to specify options for this operation (see the options.RunCmdOptions documentation).
 func (db *Database) RunCommand(ctx context.Context, runCommand interface{}, opts ...*options.RunCmdOptions) *SingleResult {
 	if ctx == nil {
 		ctx = context.Background()
@@ -182,8 +194,15 @@ func (db *Database) RunCommand(ctx context.Context, runCommand interface{}, opts
 	}
 }
 
-// RunCommandCursor runs a command on the database and returns a cursor over the resulting reader. A user can supply
-// a custom context to this method, or nil to default to context.Background().
+// RunCommandCursor executes the given command against the database and parses the response as a cursor. If the command
+// being executed does not return a cursor (e.g. insert), the command will be executed on the server and an error
+// will be returned because the server response cannot be parsed as a cursor.
+//
+// The runCommand parameter should be a document for the command to be executed. It cannot be nil.
+// This must be an order-preserving type such as bson.D. Map types such as bson.M are not valid.
+// If the command document contains a session ID or any transaction-specific fields, the behavior is undefined.
+//
+// The opts parameter can be used to specify options for this operation (see the options.RunCmdOptions documentation).
 func (db *Database) RunCommandCursor(ctx context.Context, runCommand interface{}, opts ...*options.RunCmdOptions) (*Cursor, error) {
 	if ctx == nil {
 		ctx = context.Background()
@@ -209,7 +228,8 @@ func (db *Database) RunCommandCursor(ctx context.Context, runCommand interface{}
 	return cursor, replaceErrors(err)
 }
 
-// Drop drops this database from mongodb.
+// Drop drops the database on the server. This method ignores "namespace not found" errors so it is safe to drop
+// a database that does not exist on the server.
 func (db *Database) Drop(ctx context.Context) error {
 	if ctx == nil {
 		ctx = context.Background()
@@ -254,7 +274,16 @@ func (db *Database) Drop(ctx context.Context) error {
 	return nil
 }
 
-// ListCollections returns a cursor over the collections in a database.
+// ListCollections performs a listCollections operation
+// (https://docs.mongodb.com/manual/reference/command/listCollections/) and returns a cursor over the collections in
+// the database.
+//
+// The filter parameter should be a document containing query operators and can be used to select which collections
+// are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all
+// collections.
+//
+// The opts parameter can be used to specify options for the operation (see the options.ListCollectionsOptions
+// documentation).
 func (db *Database) ListCollections(ctx context.Context, filter interface{}, opts ...*options.ListCollectionsOptions) (*Cursor, error) {
 	if ctx == nil {
 		ctx = context.Background()
@@ -314,7 +343,15 @@ func (db *Database) ListCollections(ctx context.Context, filter interface{}, opt
 	return cursor, replaceErrors(err)
 }
 
-// ListCollectionNames returns a slice containing the names of all of the collections on the server.
+// ListCollectionNames performs a listCollections operation and returns a slice containing the names of the collections
+// in the database. This method requires driver version >= 1.1.0.
+//
+// The filter parameter should be a document containing query operators and can be used to select which collections
+// are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all
+// collections.
+//
+// The opts parameter can be used to specify options for the operation (see the options.ListCollectionsOptions
+// documentation).
 func (db *Database) ListCollectionNames(ctx context.Context, filter interface{}, opts ...*options.ListCollectionsOptions) ([]string, error) {
 	opts = append(opts, options.ListCollections().SetNameOnly(true))
 
@@ -350,24 +387,34 @@ func (db *Database) ListCollectionNames(ctx context.Context, filter interface{},
 	return names, nil
 }
 
-// ReadConcern returns the read concern of this database.
+// ReadConcern returns the read concern used to configure the Database object.
 func (db *Database) ReadConcern() *readconcern.ReadConcern {
 	return db.readConcern
 }
 
-// ReadPreference returns the read preference of this database.
+// ReadPreference returns the read preference used to configure the Database object.
 func (db *Database) ReadPreference() *readpref.ReadPref {
 	return db.readPreference
 }
 
-// WriteConcern returns the write concern of this database.
+// WriteConcern returns the write concern used to configure the Database object.
 func (db *Database) WriteConcern() *writeconcern.WriteConcern {
 	return db.writeConcern
 }
 
-// Watch returns a change stream cursor used to receive information of changes to the database. This method is preferred
-// to running a raw aggregation with a $changeStream stage because it supports resumability in the case of some errors.
-// The database must have read concern majority or no read concern for a change stream to be created successfully.
+// Watch returns a change stream for all changes to the corresponding database. See
+// https://docs.mongodb.com/manual/changeStreams/ for more information about change streams.
+//
+// The Database must be configured with read concern majority or no read concern for a change stream to be created
+// successfully.
+//
+// The pipeline parameter should be a slice of documents, each representing a pipeline stage. The pipeline cannot be
+// nil but can be empty. The stage documents must all be non-nil. See https://docs.mongodb.com/manual/changeStreams/ for
+// a list of pipeline stages that can be used with change streams. For a pipeline of bson.D documents, the
+// mongo.Pipeline{} type can be used.
+//
+// The opts parameter can be used to specify options for change stream creation (see the options.ChangeStreamOptions
+// documentation).
 func (db *Database) Watch(ctx context.Context, pipeline interface{},
 	opts ...*options.ChangeStreamOptions) (*ChangeStream, error) {