clarifying definitions and builders documentation.

craiggwilson · craiggwilson · commit d78fbbecbe8f · 2015-05-11T15:08:04.000-05:00
diff --git a/Docs/reference/content/reference/driver/definitions.md b/Docs/reference/content/reference/driver/definitions.md
@@ -11,107 +11,75 @@ title = "Definitions and Builders"
 
 ## Definitions and Builders
 
-The driver has introduced a number of types related to the specification of filters, updates, projections, sorts, etc... These types are used throughout the [API]({{< relref "reference\driver\crud\index.md" >}}). In addition, most of them have builders as well to aid in their creation.
+The driver has introduced a number of types related to the specification of filters, updates, projections, sorts, and index keys. These types are used throughout the [API]({{< relref "reference\driver\crud\index.md" >}}). 
 
+Most of the definitions also have builders to aid in their creation. Each builder has a generic type parameter `TDocument` which represents the type of document with which you are working. It will almost always match the generic `TDocument` parameter used in an [`IMongoCollection<TDocument>`]({{< apiref "T_MongoDB_Driver_IMongoCollection_1" >}}).
 
-## Fields
 
-[`FieldDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_FieldDefinition_1" >}}) and [`FieldDefinition<TDocument, TField>`]({{< apiref "T_MongoDB_Driver_FieldDefinition_2" >}}) define how to get a field name. They are implicitly convertible from a string, so that you can simply pass the field name you'd like.
+## Fields
 
-For instance, with a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}), the following will be true:
+[`FieldDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_FieldDefinition_1" >}}) and [`FieldDefinition<TDocument, TField>`]({{< apiref "T_MongoDB_Driver_FieldDefinition_2" >}}) define how to get a field name. They are implicitly convertible from a string, so that you can simply pass the field name you'd like. For instance, to use the field named "fn" with a `TDocument` of [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}), do the following:
 
 ```csharp
-// method definition
-string GetFieldName<TDocument>(FieldDefinition<TDocument> field);
-
-// invocation
-var fieldName = GetFieldName<BsonDocument>("fun");
-
-fieldName.Should().Be("fun");
+FieldDefinition<BsonDocument> field = "fn";
 ```
 
-However, if you are working with a [mapped class]({{< relref "reference\bson\mapping\index.md" >}}), then 2 further options exist.
-
-First, most locations that accept a [`FieldDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_FieldDefinition_1" >}}) or [`FieldDefinition<TDocument, TField>`]({{< apiref "T_MongoDB_Driver_FieldDefinition_2" >}}) will also have an overload (via extension method) that accepts a lambda expression. Given the following class definition marked with the [`BsonElementAttribute`]({{< apiref "T_MongoDB_Bson_Serialization_Attributes_BsonElementAttribute" >}}) instructing the use of a different field name:
+However, if you are working with a [mapped class]({{< relref "reference\bson\mapping\index.md" >}}), then we are able to translate a string that equals the property name. For instance, given the below `Person` class:
 
 ```csharp
 class Person
 {
 	[BsonElement("fn")]
 	public string FirstName { get; set; }
 
-	[BsonElement("fn")]
+	[BsonElement("ln")]
 	public string LastName { get; set; }
 }
 ```
 
-Then the following will be true.
+Since we know the type is `Person`, we can provide the property name, `FirstName`, from the class and "fn" will still be used.
 
 ```csharp
-// method definition
-string GetFieldName<TDocument>(Expression<Func<TDocument, object>> field);
-
-// invocation
-var fieldName = GetFieldName<Person>(x => x.FirstName);
-
-fieldName.Should().Be("fn");
+FieldDefinition<Person> field = "FirstName";
 ```
-
-In the same way, since we know the type of document, `Person` in this case, we can also translate fields names provided as a string.
+{{% note %}}We don't validate that the provided string exists as a mapped field, so it is still possible to provide a field that hasn't been mapped:{{% /note %}}
 
 ```csharp
-// method definition
-string GetFieldName<TDocument>(FieldDefinition<TDocument> field);
-
-// invocation
-var fieldName = GetFieldName<Person>("FirstName");
-
-fieldName.Should().Be("fn");
+FieldDefinition<Person> field = "fn";
 ```
 
-Finally, we don't validate that the provided string exists as a mapped field, so it is still possible to provide a field that hasn't been mapped:
-
-```csharp
-// method definition
-string GetFieldName<TDocument>(FieldDefinition<TDocument> field);
-
-// invocation
-var fieldName = GetFieldName<Person>("fn");
-
-fieldName.Should().Be("fn");
-```
+And the output field name of this will be just "fn".
 
 
 ## Filters
 
-[`FilterDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_FilterDefinition_1" >}}) defines a filter. It is implicity convertible from both a JSON string as well as a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}). Given the following method, all the following are valid:
+[`FilterDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_FilterDefinition_1" >}}) defines a filter. It is implicity convertible from both a JSON string as well as a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}).
 
 ```csharp
-// method definition
-BsonDocument Filter(FilterDefinition<BsonDocument> filter);
+FilterDefinition<BsonDocument> filter = "{ x: 1 }";
 
-// invocation
-var doc = Filter("{ x: 1 }");
-doc.ToJson().Should().Be("{ x: 1 }");
+// or
 
-var doc = Filter(new BsonDocument("x", 1));
-doc.ToJson().Should().Be("{ x: 1 }");
+FilterDefinition<BsonDocument> filter = new BsonDocument("x", 1);
 ```
 
+Both of these will render the filter `{ x: 1 }`.
+
+
 ### Filter Definition Builder 
 
 _See the [tests]({{< srcref "MongoDB.Driver.Tests/FilterDefinitionBuilderTests.cs" >}}) for examples._
 
-The [`FilterDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_FilterDefinitionBuilder_1" >}}) provides a nice API for building up both simple and complex [MongoDB queries]({{< docsref "reference/operator/query/" >}}).
+The [`FilterDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_FilterDefinitionBuilder_1" >}}) provides a type-safe API for building up both simple and complex [MongoDB queries]({{< docsref "reference/operator/query/" >}}).
 
-For example, to build up the filter `{ x: 10, y: { $lt: 20 } }`, the following calls are all comparable.
+For example, to build up the filter `{ x: 10, y: { $lt: 20 } }`, the following calls are all equivalent.
 
 ```csharp
 var builder = Builders<BsonDocument>.Filter;
 var filter = builder.Eq("x", 10) & builder.Lt("y", 20);
 ```
 
-{{% note %}}Note that the `&` operator is overloaded. Other overloaded operators include the `|` operator for "or" and the `!` operator for "not".{{% /note %}}
+{{% note %}}The `&` operator is overloaded. Other overloaded operators include the `|` operator for "or" and the `!` operator for "not".{{% /note %}}
 
 Given the following class:
 
@@ -126,27 +94,25 @@ class Widget
 }
 ```
 
-We can achieve the same result in the typed variant:
+You can achieve the same result in the typed variant:
 
 ```csharp
 var builder = Builders<Widget>.Filter;
-var filter = builder.Eq(x => x.X, 10) & builder.Lt(x => x.Y, 20);
+var filter = builder.Eq(widget => widget.X, 10) & builder.Lt(widget => widget.Y, 20);
+```
 
-// or
+The benefits to this form is the compile-time safety inherent in using types. In addition, your IDE can provide refactoring support.
 
+Alternatively, you can elect to use a string-based field name instead.
+
+```csharp
 var filter = builder.Eq("X", 10) & builder.Lt("Y", 20);
 
 // or
 
 var filter = builder.Eq("x", 10) & builder.Lt("y", 20);
 ```
 
-Or via a lambda expression:
-
-```csharp
-var filter = Builders<Widget>.Filter.Where(x => x.X == 10 && x.Y < 20);
-```
-
 For more information on valid lambda expressions, see the [expressions documentation]({{< relref "reference\driver\expressions.md" >}}).
 
 #### Array Operators 
@@ -190,13 +156,26 @@ PipelineDefinition pipeline = new BsonDocument[]
 
 ## Projections
 
-There are two forms of a projection definition, one where the type of the projection is known ([`ProjectionDefinition<TDocument, TProjection>`]({{< apiref "T_MongoDB_Driver_ProjectionDefinition_2" >}})) and one where the type of the projection is not yet known ([`ProjectionDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_ProjectionDefinition_1" >}})). The latter, while implicitly convertible to the first, is merely used as a building block. The [high-level APIs]({{< relref "reference\driver\crud\index.md" >}}) that take a projection will always take the former. This is because, when determining how to handle a projection client-side, it is not enough to know what fields and transformations will take place. It also requires that we know how to interpret the projected shape as a .NET type. Since the driver allows you to work with custom classes, it is imperative that any projection also include the "interpretation instructions" for projecting into a custom class.
+There are two forms of a projection definition: one where the type of the projection is known, [`ProjectionDefinition<TDocument, TProjection>`]({{< apiref "T_MongoDB_Driver_ProjectionDefinition_2" >}}), and one where the type of the projection is not yet known, [`ProjectionDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_ProjectionDefinition_1" >}}). The latter, while implicitly convertible to the first, is merely used as a building block. The [high-level APIs]({{< relref "reference\driver\crud\index.md" >}}) that take a projection will always take the former. This is because, when determining how to handle a projection client-side, it is not enough to know what fields and transformations will take place. It also requires that we know how to interpret the projected shape as a .NET type. Since the driver allows you to work with custom classes, it is imperative that any projection also include the "interpretation instructions" for projecting into a custom class.
+
+Each projection definition is implicity convertible from both a JSON string as well as a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}).
+
+```csharp
+ProjectionDefinition<BsonDocument> projection = "{ x: 1 }";
+
+// or
+
+ProjectionDefinition<BsonDocument> projection = new BsonDocument("x", 1);
+```
+
+Both of these will render the projection `{ x: 1 }`.
+
 
 ### Projection Definition Builder 
 
 _See the [tests]({{< srcref "MongoDB.Driver.Tests/ProjectionDefinitionBuilderTests.cs" >}}) for examples._
 
-The [`ProjectionDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_ProjectionDefinitionBuilder_1" >}}) exists to make it easier to build up projections in MongoDB's syntax. To render the projection `{ x: 1, y: 1, _id: 0 }`, the following should be done:
+The [`ProjectionDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_ProjectionDefinitionBuilder_1" >}}) exists to make it easier to build up projections in MongoDB's syntax. For the projection `{ x: 1, y: 1, _id: 0 }`:
 
 ```csharp
 var projection = Builders<BsonDocument>.Projection.Include("x").Include("y").Exclude("_id");
@@ -295,25 +274,23 @@ A projection is also used when performing grouping in the [Aggregation Framework
 
 ## Sorts
 
-[`SortDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_SortDefinition_1" >}}) defines how to render a valid sort document. It is implicity convertible from both a JSON string as well as a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}). Given the following method, all the following are valid:
+[`SortDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_SortDefinition_1" >}}) defines how to render a valid sort document. It is implicity convertible from both a JSON string as well as a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}).
 
 ```csharp
-// method definition
-BsonDocument Sort(SortDefinition<BsonDocument> filter);
+SortDefinition<BsonDocument> sort = "{ x: 1 }";
 
-// invocation
-var doc = Sort("{ x: 1 }");
-doc.ToJson().Should().Be("{x : 1 }");
+// or
 
-var doc = Sort(new BsonDocument("x", 1));
-doc.ToJson().Should().Be("{ x: 1 }");
+SortDefinition<BsonDocument> sort = new BsonDocument("x", 1);
 ```
 
+Both of these will render the sort `{ x: 1 }`.
+
 ### Sort Definition Builder 
 
 _See the [tests]({{< srcref "MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs" >}}) for examples._
 
-The [`SortDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_SortDefinitionBuilder_1" >}}) provides a nice API for building up [MongoDB sort syntax]({{< docsref "reference/method/cursor.sort/" >}}).
+The [`SortDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_SortDefinitionBuilder_1" >}}) provides a type-safe API for building up [MongoDB sort syntax]({{< docsref "reference/method/cursor.sort/" >}}).
 
 For example, to build up the sort `{ x: 1, y: -1 }`, do the following:
 
@@ -353,25 +330,25 @@ var sort = builder.Ascending("x").Descending("y");
 
 ## Updates
 
-[`UpdateDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_UpdateDefinition_1" >}}) defines how to render a valid update document. It is implicity convertible from both a JSON string as well as a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}). Given the following method, all the following are valid:
+[`UpdateDefinition<TDocument>`]({{< apiref "T_MongoDB_Driver_UpdateDefinition_1" >}}) defines how to render a valid update document. It is implicity convertible from both a JSON string as well as a [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}). 
 
 ```csharp
-// method definition
-BsonDocument Update(UpdateDefinition<BsonDocument> filter);
-
 // invocation
-var doc = Update("{ $set: { x: 1 } }");
-doc.ToJson().Should().Be("{ $set: { x: 1 } }");
+UpdateDefinition<BsonDocument> update = "{ $set: { x: 1 } }";
+
+// or
 
-var doc = Sort(new BsonDocument("$set", new BsonDocument("x", 1)));
-doc.ToJson().Should().Be("{ $set: { x: 1 } }");
+UpdateDefinition<BsonDocument> update = new BsonDocument("$set", new BsonDocument("x", 1));
 ```
 
+Both of these will render the update `{ $set: { x: 1 } }`.
+
+
 ### Update Definition Builder 
 
 _See the [tests]({{< srcref "MongoDB.Driver.Tests/UpdateDefinitionBuilderTests.cs" >}}) for examples._
 
-The [`UpdateDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_UpdateDefinitionBuilder_1" >}}) provides a nice API for building the [MongoDB update specification]({{< docsref "reference/operator/update/" >}}).
+The [`UpdateDefinitionBuilder<TDocument>`]({{< apiref "T_MongoDB_Driver_UpdateDefinitionBuilder_1" >}}) provides a type-safe API for building the [MongoDB update specification]({{< docsref "reference/operator/update/" >}}).
 
 For example, to build up the update `{ $set: { x: 1, y: 3 }, $inc: { z: 1 } }`, do the following:
 
@@ -400,7 +377,7 @@ We can achieve the same result in a typed variant:
 
 ```csharp
 var builder = Builders<Widget>.Update;
-var update = builder.Set(x => x.X, 1).Set(x => x.Y, 3).Inc(x => x.Z, 1);
+var update = builder.Set(widget => widget.X, 1).Set(widget => widget.Y, 3).Inc(widget => widget.Z, 1);
 
 // or
 
