CR Changes

Author: craiggwilson

Docs/reference/content/reference/bson/mapping/index.md

@@ -620,7 +620,7 @@ BsonClassMap.RegisterClassMap<Employee>(cm =>
 
 #### Enums
 
-Another case that deserves mention is enumerations. Enumerations are, by default, represented as their base value. In other words, a plain enum will be represented as an integer value. However, it is possible to instruct the driver to represent an enum as a string.
+Another case that deserves mention is enums. Enums are, by default, represented as their underlying value. In other words, a plain enum will be represented as an integer value. However, it is possible to instruct the driver to represent an enum as a string.
 
 ```csharp
 public enum Color

Docs/reference/content/reference/driver/crud/writing.md

@@ -92,7 +92,7 @@ var result = await collection.DeleteManyAsync(filter);
 
 ## Find And Modify
 
-There are a certain class of operations using the [findAndModify command]({{< docsref "reference/command/findAndModify/" >}}) from the server. This command will perform some operation on the document and return the document either before or after the modification takes place. By default, the document is returned before the modification takes place.
+There are a certain class of operations using the [findAndModify command]({{< docsref "reference/command/findAndModify/" >}}) from the server. This command will perform some operation on the document and return either the original version of the document as it was before the operation, or the new version of the document as it became after the operation. By default, the original version of the document is returned.
 
 ### FindOneAndDelete
 
@@ -102,7 +102,10 @@ A single document can be deleted atomically using [`FindOneAndDeleteAsync`]({{<
 var filter = new BsonDocument("FirstName", "Jack");
 var result = await collection.FindOneAndDeleteAsync(filter);
 
-Assert(result["FirstName"] == "Jack"); // will be true if a document was found.
+if (result != null)
+{
+	Assert(result["FirstName"] == "Jack");
+}
 ```
 
 The above will find a document where the `FirstName` is `Jack` and delete it. It will then return the document that was just deleted.
@@ -118,7 +121,10 @@ var replacementDocument = new BsonDocument("FirstName", "John");
 
 var result = await collection.FindOneAndReplaceAsync(filter, doc);
 
-Assert(result["FirstName"] == "Jack"); // will be true if a document was found.
+if (result != null)
+{
+	Assert(result["FirstName"] == "Jack");
+}
 ```
 
 The above will find a document where the `FirstName` is `Jack` and replace it with `replacementDocument`. It will then return the document that was replaced.
@@ -133,7 +139,10 @@ var update = Builders<BsonDocument>.Update.Set("FirstName", "John");
 
 var result = await collection.FindOneAndUpdateAsync(filter, update);
 
-Assert(result["FirstName"] == "Jack"); // will be true if a document was found.
+if (result != null)
+{
+	Assert(result["FirstName"] == "Jack");
+}
 ```
 
 The above will find a document where the `FirstName` is `Jack` and set its `FirstName` field to `John`. It will then return the document that was replaced.
@@ -145,21 +154,24 @@ Each of the 3 operations has certain options available.
 
 #### ReturnDocument
 
-For Replacing and Updating, the [`ReturnDocument`]({{< apiref "T_MongoDB_Driver_ReturnDocument" >}}) enum can be provided. It allows you to return the document after the modification has taken place. The default is `Before`.
+For Replacing and Updating, the [`ReturnDocument`]({{< apiref "T_MongoDB_Driver_ReturnDocument" >}}) enum can be provided. It allows you to choose which version of the document to return, either the original version as it was before the operation, or the modified version as it became after the operation.
 
 For example:
 
 ```csharp
 var filter = new BsonDocument("FirstName", "Jack");
 var update = Builders<BsonDocument>.Update.Set("FirstName", "John");
 
-var options = new FindOneAndUpdateOptions<BsonDocument, BsonDocument>
+var options = new FindOneAndUpdateOptions<BsonDocument>
 {
-	ReturnDocument = ReturnDocument.After
+    ReturnDocument = ReturnDocument.After
 };
 var result = await collection.FindOneAndUpdateAsync(filter, update, options);
 
-Assert(result["FirstName"] == "John"); // will be true if a document was found.
+if (result != null)
+{
+	Assert(result["FirstName"] == "John");
+}
 ```
 
 #### Projection
@@ -168,7 +180,7 @@ A projection can be provided to shape the result. The easiest way to build the p
 
 #### Sort
 
-Since only a single document is selected, for filters that could result in multiple choices, a sort should be provided and the first document will be selected.
+Since only a single document is selected, for filters that could result in multiple choices, a sort should be provided and the first document in the sort order will be the one modified.
 
 #### IsUpsert
 

Docs/reference/content/upgrading.md

@@ -35,10 +35,10 @@ As 2.0 is a major revision, there are some breaking changes when coming from the
 - [CSHARP-979](https://jira.mongodb.org/browse/CSHARP-979): `MongoConnectionStringBuilder` has been removed. Use the documented mongodb connection string format and/or `MongoUrlBuilder`.
 - `MongoServer` is a deprecated class. Anyone using `MongoClient.GetServer()` will encounter a deprecation warning and, depending on how your build is setup, may receive an error. It is still safe to use this API until your code is ported to the new API. *Note that this API requires the use of the [mongocsharpdriver](http://nuget.org/packages/mongocsharpdriver) to include the legacy API.
 - [CSHARP-1043](https://jira.mongodb.org/browse/CSHARP-1043) and [CSHARP-1044](https://jira.mongodb.org/browse/CSHARP-1044): `ReadPreference` and `WriteConcern` were rewritten. These classes are now immutable. Any current application code that sets values on these classes will no longer function. Instead, you should use the With method to alter a `ReadPreference` or `WriteConcern`.
-	
-	``` csharp
-	var writeConcern = myCurrentWriteConcern.With(journal: true);
-	```
+    
+    ``` csharp
+    var writeConcern = myCurrentWriteConcern.With(journal: true);
+    ```
 
 ## Migrating
 
@@ -48,13 +48,13 @@ Below are some common actions in the old API and their counterpart in the new AP
 
 _[More information.]({{< relref "reference\driver\definitions.md" >}})_
 
-The old builders (Query, Update, etc...) have all be replaced with Builders<T>.Filter, Builders<T>.Update, etc...
+The old builders (`Query`, `Update`, etc...) have all been replaced by `Builders<T>.Filter`, `Builders<T>.Update`, etc...
 
 ```csharp
 // old API
 var query = Query.And(
-	Query<Person>.EQ(x => x.FirstName, "Jack"), 
-	Query<Person>.LT(x => x.Age, 21));
+    Query<Person>.EQ(x => x.FirstName, "Jack"), 
+    Query<Person>.LT(x => x.Age, 21));
 
 // new API
 var builder = Builders<Person>.Filter;
@@ -64,20 +64,20 @@ var filter = builder.Eq(x => x.FirstName, "Jack") & builder.Lt(x => x.Age, 21);
 ```csharp
 // old API
 var update = Update.Combine(
-	Update<Person>.Set(x => x.LastName, "McJack"),
-	Update<Person>.Inc(x => x.Age, 1));
+    Update<Person>.Set(x => x.LastName, "McJack"),
+    Update<Person>.Inc(x => x.Age, 1));
 
 // new API
 var update = Builders<Person>.Update
-	.Set(x => x.LastName, "McJack")
-	.Inc(x => x.Age, 1);
+    .Set(x => x.LastName, "McJack")
+    .Inc(x => x.Age, 1);
 ```
 
 ### Finding All Documents
 
 _[More information.]({{< relref "reference\driver\crud\reading.md#finding-documents" >}})_
 
-To find all documents, you must specify an empty filter.
+To match all documents, you must specify an empty filter.
 
 ```csharp
 // old API
@@ -91,14 +91,14 @@ var list = await collection.Find(new BsonDocument()).ToListAsync();
 
 _[More information.]({{< relref "reference\driver\crud\reading.md#single-results" >}})_
 
-To find all documents, you must specify an empty filter.
+To match all documents, you must specify an empty filter.
 
 ```csharp
 // old API
-var doc = collection.FindOne();
+var document = collection.FindOne();
 
 // new API
-var doc = await collection.Find(new BsonDocument()).FirstOrDefaultAsync();
+var document = await collection.Find(new BsonDocument()).FirstOrDefaultAsync();
 ```
 
 ### Iteration
@@ -109,30 +109,30 @@ You cannot iterate synchronously using a foreach loop without first getting a li
 
 ```csharp
 // old API
-foreach(var doc in collection.Find(new QueryDocument("Name", "Jack")))
+foreach (var document in collection.Find(new QueryDocument("Name", "Jack")))
 {
-	// do something
+    // do something
 }
 
 // new API
 await collection.Find(new BsonDocument("Name", "Jack"))
-	.ForEachAsync(doc =>
-	{
-		// do something
-	});
+    .ForEachAsync(document =>
+    {
+        // do something
+    });
 
 await collection.Find(new BsonDocument("Name", "Jack"))
-	.ForEachAsync(async doc =>
-	{
-		// do something with await
-	});
+    .ForEachAsync(async document =>
+    {
+        // do something with await
+    });
 ```
 
 ### Counting All Documents
 
 _[More information.]({{< relref "reference\driver\crud\reading.md#counting-documents" >}})_
 
-To find all documents, you must specify an empty filter.
+To match all documents, you must specify an empty filter.
 
 ```csharp
 // old API
@@ -151,20 +151,20 @@ You can still use attributes as you have done before. To set the representation
 ```csharp
 class Test
 {
-	public char RepresentAsInt32 { get; set; }
+    public char RepresentAsInt32 { get; set; }
 }
 
 // old API
 BsonClassMap.RegisterClassMap<Person>(cm =>
 {
-	// snip...
-	cm.MapMember(x => x.RepresentAsInt32).SetRepresentation(BsonType.Int32);
+    // snip...
+    cm.MapMember(x => x.RepresentAsInt32).SetRepresentation(BsonType.Int32);
 });
 
 // new API
 BsonClassMap.RegisterClassMap<Person>(cm =>
 {
-	// snip...
-	cm.MapMember(x => x.RepresentAsInt32).SetSerializer(new CharSerializer(BsonType.Int32));
+    // snip...
+    cm.MapMember(x => x.RepresentAsInt32).SetSerializer(new CharSerializer(BsonType.Int32));
 });
 ```