GODRIVER-1811 mongo/doc.go improvements (mongodb#563)

README.md

@@ -45,7 +45,7 @@ dep ensure -add "go.mongodb.org/mongo-driver/mongo"
 -------------------------
 ## Usage
 
-To get started with the driver, import the `mongo` package, create a `mongo.Client`:
+To get started with the driver, import the `mongo` package and create a `mongo.Client` with the `Connect` function:
 
 ```go
 import (
@@ -54,20 +54,6 @@ import (
     "go.mongodb.org/mongo-driver/mongo/readpref"
 )
 
-client, err := mongo.NewClient(options.Client().ApplyURI("mongodb://localhost:27017"))
-```
-
-And connect it to your running MongoDB server:
-
-```go
-ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-defer cancel()
-err = client.Connect(ctx)
-```
-
-To do this in a single step, you can use the `Connect` function:
-
-```go
 ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 defer cancel()
 client, err := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://localhost:27017"))
@@ -105,11 +91,11 @@ The `Collection` instance can then be used to insert documents:
 ```go
 ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
 defer cancel()
-res, err := collection.InsertOne(ctx, bson.M{"name": "pi", "value": 3.14159})
+res, err := collection.InsertOne(ctx, bson.D{{"name", "pi"}, {"value", 3.14159}})
 id := res.InsertedID
 ```
 
-To use `bson.M`, you will need to add `"go.mongodb.org/mongo-driver/bson"` to your imports.
+To use `bson.D`, you will need to add `"go.mongodb.org/mongo-driver/bson"` to your imports.
 
 Your import statement should now look like this:
 
@@ -131,7 +117,7 @@ cur, err := collection.Find(ctx, bson.D{})
 if err != nil { log.Fatal(err) }
 defer cur.Close(ctx)
 for cur.Next(ctx) {
-   var result bson.M
+   var result bson.D
    err := cur.Decode(&result)
    if err != nil { log.Fatal(err) }
    // do something with result....
@@ -147,7 +133,7 @@ For methods that return a single item, a `SingleResult` instance is returned:
 var result struct {
     Value float64
 }
-filter := bson.M{"name": "pi"}
+filter := bson.D{{"name", "pi"}}
 ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
 defer cancel()
 err = collection.FindOne(ctx, filter).Decode(&result)
@@ -160,9 +146,11 @@ if err != nil {
 Additional examples and documentation can be found under the examples directory and [on the MongoDB Documentation website](https://docs.mongodb.com/drivers/go/).
 
 -------------------------
-## Bugs / Feature Reporting
+## Feedback
+
+For help with the driver, please post in the [MongoDB Community Forums](https://developer.mongodb.com/community/forums/tag/golang/).
 
-New Features and bugs can be reported on jira: https://jira.mongodb.org/browse/GODRIVER
+New features and bugs can be reported on jira: https://jira.mongodb.org/browse/GODRIVER
 
 -------------------------
 ## Testing / Development
@@ -178,17 +166,17 @@ For example, for a local replica set named `rs1` comprised of three nodes on por
 MONGODB_URI="mongodb://localhost:27017,localhost:27018,localhost:27018/?replicaSet=rs1" make
 ```
 
-### Testing Auth and SSL
+### Testing Auth and TLS
 
-To test authentication and SSL, first set up a MongoDB cluster with auth and SSL configured. Testing authentication requires a user with the `root` role on the `admin` database. The Go Driver repository comes with example certificates in the `data/certificates` directory. These certs can be used for testing. Here is an example command that would run a mongod with SSL correctly configured for tests:
+To test authentication and TLS, first set up a MongoDB cluster with auth and TLS configured. Testing authentication requires a user with the `root` role on the `admin` database. The Go Driver repository comes with example certificates in the `data/certificates` directory. These certs can be used for testing. Here is an example command that would run a mongod with TLS correctly configured for tests:
 
 ```
 mongod \
 --auth \
---sslMode requireSSL \
---sslPEMKeyFile $(pwd)/data/certificates/server.pem \
---sslCAFile $(pwd)/data/certificates/ca.pem \
---sslWeakCertificateValidation
+--tlsMode requireTLS \
+--tlsCertificateKeyFile $(pwd)/data/certificates/server.pem \
+--tlsCAFile $(pwd)/data/certificates/ca.pem \
+--tlsAllowInvalidCertificates
 ```
 
 To run the tests with `make`, set `MONGO_GO_DRIVER_CA_FILE` to the location of the CA file used by the database, set `MONGODB_URI` to the connection string of the server, set `AUTH=auth`, and set `SSL=ssl`. For example:
@@ -198,7 +186,7 @@ AUTH=auth SSL=ssl MONGO_GO_DRIVER_CA_FILE=$(pwd)/data/certificates/ca.pem  MONGO
 ```
 
 Notes:
-- The `--sslWeakCertificateValidation` flag is required on the server for the test suite to work correctly.
+- The `--tlsAllowInvalidCertificates` flag is required on the server for the test suite to work correctly.
 - The test suite requires the auth database to be set with `?authSource=admin`, not `/admin`.
 
 ### Testing Compression
@@ -212,10 +200,9 @@ MONGO_GO_DRIVER_COMPRESSOR=snappy make
 Ensure the [`--networkMessageCompressors` flag](https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-networkmessagecompressors) on mongod or mongos includes `zlib` if testing zLib compression.
 
 -------------------------
-## Feedback
+## Contribution
 
-The MongoDB Go Driver is not feature complete, so any help is appreciated. Check out the [project page](https://jira.mongodb.org/browse/GODRIVER)
-for tickets that need completing. See our [contribution guidelines](CONTRIBUTING.md) for details.
+Check out the [project page](https://jira.mongodb.org/browse/GODRIVER) for tickets that need completing. See our [contribution guidelines](CONTRIBUTING.md) for details.
 
 -------------------------
 ## Continuous Integration

mongo/doc.go

@@ -9,14 +9,12 @@
 // Package mongo provides a MongoDB Driver API for Go.
 //
 // Basic usage of the driver starts with creating a Client from a connection
-// string. To do so, call the NewClient and Connect functions:
+// string. To do so, call Connect:
 //
-// 		client, err := NewClient(options.Client().ApplyURI("mongodb://foo:bar@localhost:27017"))
-// 		if err != nil { return err }
-// 		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
-// 		defer cancel()
-// 		err = client.Connect(ctx)
-// 		if err != nil { return err }
+//    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+//    defer cancel()
+//    client, err := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://foo:bar@localhost:27017"))
+//    if err != nil { return err }
 //
 // This will create a new client and start monitoring the MongoDB server on localhost.
 // The Database and Collection types can be used to access the database:
@@ -52,6 +50,17 @@
 //      return err
 //    }
 //
+// Cursor.All will decode all of the returned elements at once:
+//
+//    var results []struct{
+//      Foo string
+//      Bar int32
+//    }
+//    if err = cur.All(context.Background(), &results); err != nil {
+//      log.Fatal(err)
+//    }
+//    // do something with results...
+//
 // Methods that only return a single document will return a *SingleResult, which works
 // like a *sql.Row:
 //