From 282add350a7b55be933ca0be7acedcca91d3e843 Mon Sep 17 00:00:00 2001
From: Thijs Cadier <thijs@appsignal.com>
Date: Sat, 23 Jan 2016 17:10:24 +0100
Subject: [PATCH] Change write concern new to default and document it

---
 src/collection.rs      | 10 +++++-----
 src/write_concern.rs   | 30 +++++++++++++++++++++++++++++-
 tests/write_concern.rs |  4 ++--
 3 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/src/collection.rs b/src/collection.rs
index cf345e3..3310641 100644
--- a/src/collection.rs
+++ b/src/collection.rs
@@ -55,7 +55,7 @@ impl BulkOperationOptions {
     pub fn default() -> BulkOperationOptions {
         BulkOperationOptions {
             ordered:       false,
-            write_concern: WriteConcern::new()
+            write_concern: WriteConcern::default()
         }
     }
 }
@@ -138,7 +138,7 @@ impl InsertOptions {
     pub fn default() -> InsertOptions {
         InsertOptions {
             insert_flags:  Flags::new(),
-            write_concern: WriteConcern::new()
+            write_concern: WriteConcern::default()
         }
     }
 }
@@ -156,7 +156,7 @@ impl RemoveOptions {
     pub fn default() -> RemoveOptions {
         RemoveOptions {
             remove_flags:  Flags::new(),
-            write_concern: WriteConcern::new()
+            write_concern: WriteConcern::default()
         }
     }
 }
@@ -174,7 +174,7 @@ impl UpdateOptions {
     pub fn default() -> UpdateOptions {
         UpdateOptions {
             update_flags:  Flags::new(),
-            write_concern: WriteConcern::new()
+            write_concern: WriteConcern::default()
         }
     }
 }
@@ -573,7 +573,7 @@ impl<'a> Collection<'a> {
     ) -> Result<()> {
         assert!(!self.inner.is_null());
 
-        let default_write_concern = WriteConcern::new();
+        let default_write_concern = WriteConcern::default();
         let write_concern         = write_concern.unwrap_or(&default_write_concern);
 
         let mut error = BsoncError::empty();
diff --git a/src/write_concern.rs b/src/write_concern.rs
index 219bb6b..9e1f3cd 100644
--- a/src/write_concern.rs
+++ b/src/write_concern.rs
@@ -1,16 +1,44 @@
+//! Abstraction on top of the MongoDB connection write concern.
+
 use mongoc::bindings;
 
+/// Possible write concern levels, only default is supported at the moment.
+pub enum WriteConcernLevel {
+    /// By default, writes block awaiting acknowledgment from MongoDB. Acknowledged write concern allows clients to catch network, duplicate key, and other errors.
+    Default,
+
+    // We'd like to support the following write concerns too at some point, pull request welcome:
+
+    // With this write concern, MongoDB does not acknowledge the receipt of write operation. Unacknowledged is similar to errors ignored; however, mongoc attempts to receive and handle network errors when possible.
+    // WriteUnacknowledged,
+    // Block until a write has been propagated to a majority of the nodes in the replica set.
+    // Majority,
+    // Block until a write has been propagated to at least n nodes in the replica set.
+    // AtLeastNumberOfNodes(u32),
+    // Block until the node receiving the write has committed the journal.
+    // Journal
+}
+
+/// This tells the driver what level of acknowledgment to await from the server.
+/// The default, `Default`, is right for the great majority of applications.
 pub struct WriteConcern {
     inner: *mut bindings::mongoc_write_concern_t
 }
 
 impl WriteConcern {
-    pub fn new() -> WriteConcern {
+    /// Get the default write concern
+    pub fn default() -> WriteConcern {
+        Self::new(WriteConcernLevel::Default)
+    }
+
+    /// Create a new write concern
+    pub fn new(_: WriteConcernLevel) -> WriteConcern {
         let inner = unsafe { bindings::mongoc_write_concern_new() };
         assert!(!inner.is_null());
         WriteConcern { inner: inner }
     }
 
+    #[doc(hidden)]
     pub fn inner(&self) -> *const bindings::mongoc_write_concern_t {
         assert!(!self.inner.is_null());
         self.inner
diff --git a/tests/write_concern.rs b/tests/write_concern.rs
index f55cd3c..04987b9 100644
--- a/tests/write_concern.rs
+++ b/tests/write_concern.rs
@@ -1,7 +1,7 @@
 use mongo_driver::write_concern::WriteConcern;
 
 #[test]
-fn test_write_concern() {
-    let write_concern = WriteConcern::new();
+fn test_default_write_concern() {
+    let write_concern = WriteConcern::default();
     assert!(!write_concern.inner().is_null());
 }