CSHARP-1395: Add links to GridFS docs and other code review changes.

Author: rstam

Docs/reference/content/reference/gridfs/deletingandrenamingfiles.md

@@ -1,5 +1,5 @@
 +++
-date = "2015-09-41T00:00:00Z"
+date = "2015-09-14T00:00:00Z"
 draft = false
 title = "Deleting and Renaming Files"
 [menu.main]
@@ -15,9 +15,9 @@ These methods allow you to delete or rename GridFS files.
 
 ### Deleting a single file
 
-The DeleteAsync method is used to delete a single file identified by its Id.
+The [`DeleteAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_DeleteAsync_1" >}}) method is used to delete a single file identified by its Id.
 
-```
+```csharp
 IGridFSBucket bucket;
 ObjectId id;
 
@@ -26,21 +26,21 @@ await bucket.DeleteAsync(id);
 
 ### Dropping an entire GridFS bucket
 
-If you want to drop an entire GridFS bucket at once use the DropAsync method.
+If you want to drop an entire GridFS bucket at once use the [`DropAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_DropAsync" >}}) method.
 
-```
+```csharp
 IGridFSBucket bucket;
 
 await bucket.DropAsync();
 ```
 
-The "fs.files" collection will be dropped first, followed by the "fs.chunks" collection. This is the fastest way to delete all files stored in a GridFS bucket at once.
+{{% note %}}The "fs.files" collection will be dropped first, followed by the "fs.chunks" collection. This is the fastest way to delete all files stored in a GridFS bucket at once.{{% /note %}}
 
 ### Renaming a single file
 
-The RenameAsync method is used to rename a single file identified by its Id.
+The [`RenameAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_RenameAsync_1" >}}) method is used to rename a single file identified by its Id.
 
-```
+```csharp
 IGridFSBucket bucket;
 ObjectId id;
 string newFilename;
@@ -50,9 +50,9 @@ await bucket.RenameAsync(id, newFilename);
 
 ### Renaming all revisions of a file
 
-If you want to rename all revisions of a file you first use FindAsync to find their ids and then call RenameAsync in a loop to rename them one at a time.
+If you want to rename all revisions of a file you first use [`FindAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_FindAsync" >}}) to find their ids and then call [`RenameAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_RenameAsync_1" >}}) in a loop to rename them one at a time.
 
-```
+```csharp
 IGridFSBucket bucket;
 ObjectId id;
 string oldFilename;

Docs/reference/content/reference/gridfs/downloadingfiles.md

@@ -1,5 +1,5 @@
 +++
-date = "2015-09-41T00:00:00Z"
+date = "2015-09-14T00:00:00Z"
 draft = false
 title = "Downloading Files"
 [menu.main]
@@ -13,14 +13,14 @@ title = "Downloading Files"
 
 There are several ways to download a file from GridFS. The two main approaches are:
 
-1. The driver downloads a file as a byte array or by writing the contents to a Stream provided by the application
-2. The driver supplies a Stream object that the application can read the contents from
+1. The driver downloads a file as a byte array or by writing the contents to a [`Stream`]({{< msdnref "system.io.stream" >}}) provided by the application
+2. The driver supplies a [`Stream`]({{< msdnref "system.io.stream" >}}) object that the application can read the contents from
 
 ### Downloading as a byte array
 
 This is the easiest way to download a file from GridFS, assuming that the file is small enough for the entire contents to be held in memory at once.
 
-```
+```csharp
 IGridFSBucket bucket;
 ObjectId id;
 
@@ -29,23 +29,25 @@ var bytes = await bucket.DownloadAsBytesAsync(id);
 
 ### Downloading to a Stream
 
-If you don't want to hold the entire contents of the downloaded file in memory at once, you can have the driver write the contents of the file to a Stream provided by the application.
+If you don't want to hold the entire contents of the downloaded file in memory at once, you can have the driver write the contents of the file to a [`Stream`]({{< msdnref "system.io.stream" >}}) provided by the application.
 
-```
+```csharp
 IGridFSBucket bucket;
 ObjectId id;
 Stream destination;
 
 await bucket.DownloadToStreamAsync(id, destination);
 ```
 
-The driver will download the contents of the GridFS file and write them to the destination Stream. The driver begins writing the contents at the current position of the Stream, and does **not** close the Stream when it is done. The Stream is owned by the application and it is up to the application to close the Stream when it is ready to do so.
+The driver will download the contents of the GridFS file and write them to the destination [`Stream`]({{< msdnref "system.io.stream" >}}). The driver begins writing the contents at the current position of the [`Stream`]({{< msdnref "system.io.stream" >}}).
+
+{{% note class="important" %}}The driver does **not** close the [`Stream`]({{< msdnref "system.io.stream" >}}) when it is done. The [`Stream`]({{< msdnref "system.io.stream" >}}) is owned by the application and it is up to the application to close the [`Stream`]({{< msdnref "system.io.stream" >}}) when it is ready to do so.{{% /note %}}
 
 ### Downloading from a Stream
 
-In some cases it the application might prefer to read the contents of the GridFS file from a Stream.
+In some cases the application might prefer to read the contents of the GridFS file from a [`Stream`]({{< msdnref "system.io.stream" >}}).
 
-```
+```csharp
 IGridFSBucket bucket;
 ObjectId id;
 
@@ -56,25 +58,25 @@ using (var stream = await bucket.OpenDownloadStreamAsync(id))
 }
 ```
 
-The Stream object returned by OpenDownloadStreamAsync is actually a GridFSDownloadStream (a subclass of Stream), which has the following additional members in addition to those found in Stream:
+The [`Stream`]({{< msdnref "system.io.stream" >}}) object returned by [`OpenDownloadStreamAsync`]({{< apiref "M_MongoDB_Driver_GridFS_OpenDownloadStreamAsync_1." >}}) is actually a [`GridFSDownloadStream`]({{< apiref "T_MongoDB_Driver_GridFS_GridFSDownloadStream" >}}) (a subclass of [`Stream`]({{< msdnref "system.io.stream" >}})), which has the following additional members in addition to those found in [`Stream`]({{< msdnref "system.io.stream" >}}):
 
-```
+```csharp
 public abstract class GridFSDownloadStream : Stream
 {
     public abstract GridFSFileInfo FileInfo { get; }
     public abstract Task CloseAsync(CancellationToken cancellationToken = default(CancellationToken));
 };
 ```
 
-The FileInfo property contains information about the GridFS file being dowloaded. See the FindAsync method for details about the GridFSFileInfo class.
+The [`FileInfo`]({{< apiref "P_MongoDB_Driver_GridFS_GridFSDownloadStream_FileInfo" >}}) property contains information about the GridFS file being dowloaded. See the [`FindAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_FindAsync" >}}) method for details about the [`GridFSFileInfo`]({{< apiref "T_MongoDB_Driver_GridFS_GridFSFileInfo" >}}) class.
 
-Calling CloseAsync is optional, but recommended. Since Stream is IDisposable and it is used inside a using statement, it would be closed automatically when Dispose is called. However, in async programming we want to avoid blocking and calling CloseAsync first allows the Stream to be closed with an async call. If you call CloseAsync first then Dispose will no longer block.
+{{% note %}}Calling [`CloseAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSDownloadStream_CloseAsync." >}}) is optional, but recommended. Since [`Stream`]({{< msdnref "system.io.stream" >}}) is [`IDisposable`]({{< msdnref "system.idisposable" >}}) and it is used inside a using statement, it would be closed automatically when [`Dispose`]({{< msdnref "system.idisposable.dispose" >}}) is called. However, in async programming we want to avoid blocking and calling [`CloseAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSDownloadStream_CloseAsync." >}}) first allows the [`Stream`]({{< msdnref "system.io.stream" >}}) to be closed with an async call. If you call [`CloseAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSDownloadStream_CloseAsync." >}}) first then [`Dispose`]({{< msdnref "system.idisposable.dispose" >}}) will no longer block.{{% /note %}}
 
-By default the driver assumes that you want to read the entire contents of the file from beginning to end, and returns a Stream implementation that does not support seeking, which allows for a more efficient implementation.
+By default the driver assumes that you want to read the entire contents of the file from beginning to end, and returns a [`Stream`]({{< msdnref "system.io.stream" >}}) implementation that does not support seeking, which allows for a more efficient implementation.
 
-If you do want to use Seek with the returned Stream, you can use the options parameter to indicate that.
+If you do want to use [`Seek`]({{< msdnref "system.io.stream.seek" >}}) with the returned [`Stream`]({{< msdnref "system.io.stream" >}}), you can use the options parameter to indicate that.
 
-```
+```csharp
 IGridFSBucket bucket;
 ObjectId id;
 
@@ -107,7 +109,7 @@ The default value for the revision is -1 (i.e. the newest revision).
 
 The following examples all download the newest revision:
 
-```
+```csharp
 IGridFSBucket bucket;
 string filename;
 
@@ -129,7 +131,7 @@ using (var stream = await bucket.OpenDownloadStreamByNameAsync(filename))
 
 If you want to download a different revision, you specify the desired revision using the options parameter.
 
-```
+```csharp
 IGridFSBucket bucket;
 string filename;
 

Docs/reference/content/reference/gridfs/findingfiles.md

@@ -1,5 +1,5 @@
 +++
-date = "2015-09-41T00:00:00Z"
+date = "2015-09-14T00:00:00Z"
 draft = false
 title = "Finding Files"
 [menu.main]
@@ -15,11 +15,11 @@ Each file stored in GridFS has a unique Id assigned to it, and that is the prima
 
 ### FindAsync method
 
-If you don't know the Id, you can use FindAsync to find matching files using a filter. The filter must be of type FilterDefinition<GridFSFileInfo>.
+If you don't know the Id, you can use [`FindAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_FindAsync" >}}) to find matching files using a filter. The filter must be of type [`FilterDefinition<GridFSFileInfo>`]({{< apiref "T_MongoDB_Driver_FilterDefinition_1" >}}).
 
-For example, to find the newest revision of the file named "securityvideo" uploaded in January 2015 we could use FindAsync like this:
+For example, to find the newest revision of the file named "securityvideo" uploaded in January 2015 we could use [`FindAsync`]({{< apiref "M_MongoDB_Driver_GridFS_GridFSBucket_FindAsync" >}}) like this:
 
-```
+```csharp
 IGridFSBucket bucket;
 var filter = Builders<GridFSFileInfo>.Filter.And( 
     Builders<GridFSFileInfo>.Filter.EQ(x => x.Filename, "securityvideo"),
@@ -41,29 +41,8 @@ using (var cursor = await bucket.FindAsync(filter, options))
 
 ### GridFSFileInfo class
 
-The GridFSFileInfo is a strongly typed class that represents the information about a GridFS file stored in the "fs.files" collection.
-
-It is defined as:
-
-```
-public class GridFSFileInfo
-{
-    public BsonDocument BackingDocument { get; }
-    public int ChunkSizeBytes { get; }
-    public string Filename { get; }
-    public ObjectId Id { get; }
-    public long Length { get; }
-    public string MD5 { get; }
-    public BsonDocument Metadata { get; }
-    public DateTime UploadDateTime { get; }
-    
-    // the following are deprecated but kept for backward compatibility
-    public IEnumerable<string> Aliases { get; }
-    public string ContentType { get; }
-    public BsonValue IdAsBsonValue { get; }
-}
-```
+The [`GridFSFileInfo`]({{< apiref "T_MongoDB_Driver_GridFS_GridFSFileInfo" >}}) is a strongly typed class that represents the information about a GridFS file stored in the "fs.files" collection.
 
-This class is a strongly typed wrapper around a backing BsonDocument. It makes it easier to extract the information available in a files collection documents.
+This class is a strongly typed wrapper around a backing [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}). It makes it easier to extract the information available in a files collection documents.
 
-In older drivers it was possible to store arbitrary information at the root level of a files collection document. If you need to access that information you can use the BackingDocument property to get access to the complete backing document. When uploading new GridFS files you should store any additional information you want to associate with the uploaded file inside the Metadata document.
+In older drivers it was possible to store arbitrary information at the root level of a files collection document. If you need to access that information you can use the [`BackingDocument`]({{< apiref "P_MongoDB_Driver_GridFS_GridFSFileInfo_BackingDocument" >}}) property to get access to the complete backing document. When uploading new GridFS files you should store any additional information you want to associate with the uploaded file inside the [`Metadata`]({{< apiref "P_MongoDB_Driver_GridFS_GridFSFileInfo_Metadata" >}}) document.

Docs/reference/content/reference/gridfs/gettingstarted.md

@@ -1,5 +1,5 @@
 +++
-date = "2015-09-41T00:00:00Z"
+date = "2015-09-14T00:00:00Z"
 draft = false
 title = "Getting Started"
 [menu.main]
@@ -11,25 +11,27 @@ title = "Getting Started"
 
 ## Getting Started
 
-GridFS files are stored in the database using two collections, normally called "fs.files" and "fs.chunks". Each file uploaded to GridFS has one document in the "fs.files" containing information about the file and as many chunks as necessary in the "fs.chunks" collection to store the contents of the file.
+GridFS files are stored in the database using two collections, normally called "fs.files" and "fs.chunks". Each file uploaded to GridFS has one document in the "fs.files" collection containing information about the file and as many chunks as necessary in the "fs.chunks" collection to store the contents of the file.
 
 A GridFS "bucket" is the combination of an "fs.files" and "fs.chunks" collection which together represent a bucket where GridFS files can be stored.
 
 ### GridFSBucket
 
-A GridFSBucket object is the root object representing a GridFS bucket. You should always use a GridFSBucket object to interact with GridFS instead of directly referencing the underlying collections.
+A [`GridFSBucket`]({{< apiref "T_MongoDB_Driver_GridFS_GridFSBucket" >}}) object is the root object representing a GridFS bucket. 
 
-You create a GridFSBucket instance by calling its constructor:
+{{% note class="warning" %}}You should always use a [`GridFSBucket`]({{< apiref "T_MongoDB_Driver_GridFS_GridFSBucket" >}}) object to interact with GridFS instead of directly referencing the underlying collections.{{% /note %}}
 
-```
+You create a [`GridFSBucket`]({{< apiref "T_MongoDB_Driver_GridFS_GridFSBucket" >}}) instance by calling its constructor:
+
+```csharp
 IMongoDatabase database;
 
 var bucket = new GridFSBucket(database);
 ```
 
-You can also provide options when instantiating the GridFSBucket object:
+You can also provide options when instantiating the [`GridFSBucket`]({{< apiref "T_MongoDB_Driver_GridFS_GridFSBucket" >}}) object:
 
-```
+```csharp
 IMongoDatabase database;
 
 var bucket = new GridFSBucket(database, new GridFSOptions
@@ -41,8 +43,8 @@ var bucket = new GridFSBucket(database, new GridFSOptions
 });
 ```
 
-The BucketName value is the root part of the files and chunks collection names, so in this example the two collections would be named "videos.files" and "videos.chunks" instead of "fs.files" and "fs.chunks".
+The [`BucketName`]({{< apiref "P_MongoDB_Driver_GridFS_GridFSBucketOptions_BucketName" >}}) value is the root part of the files and chunks collection names, so in this example the two collections would be named "videos.files" and "videos.chunks" instead of "fs.files" and "fs.chunks".
 
-The ChunkSizeBytes value defines the size of each chunk, and in this example we are overriding the default value of 261120 (255MB).
+The [`ChunkSizeBytes`]({{< apiref "P_MongoDB_Driver_GridFS_GridFSBucketOptions_ChunkSizeBytes" >}}) value defines the size of each chunk, and in this example we are overriding the default value of 261120 (255MB).
 
-The WriteConcern is used when uploading files to GridFS, and the ReadPreference is used when downloading files from GridFS.
+The [`WriteConcern`]({{< apiref "P_MongoDB_Driver_GridFS_GridFSBucketOptions_WriteConcern" >}}) is used when uploading files to GridFS, and the [`ReadPreference`]({{< apiref "P_MongoDB_Driver_GridFS_GridFSBucketOptions_ReadPreference" >}}) is used when downloading files from GridFS.

Docs/reference/content/reference/gridfs/index.md

@@ -11,7 +11,7 @@ title = "GridFS"
 
 ## GridFS
 
-GridFS is a way of storing binary information that is larger than the maximum document size (currently 16MB). When you upload a file to GridFS the file is broken into chunks and the individual chunks are uploaded. When you download a  file from GridFS the original content is reassembled from the chunks.
+GridFS is a way of storing binary information larger than the maximum document size (currently 16MB). When you upload a file to GridFS the file is broken into chunks and the individual chunks are uploaded. When you download a  file from GridFS the original content is reassembled from the chunks.
 
 - [Getting Started]({{< relref "reference\gridfs\gettingstarted.md" >}})
 - [Uploading files]({{< relref "reference\gridfs\uploadingfiles.md" >}})