RUST-867 Document some performance best practices (mongodb#466)

src/client/mod.rs

@@ -69,6 +69,14 @@ const DEFAULT_SERVER_SELECTION_TIMEOUT: Duration = Duration::from_secs(30);
 /// # Ok(())
 /// # }
 /// ```
+/// ## Notes on performance
+/// Spawning many asynchronous tasks that use the driver concurrently like this is often the best
+/// way to achieve maximum performance, as the driver is designed to work well in such situations.
+///
+/// Additionally, using a custom Rust type that implements `Serialize` and `Deserialize` as the
+/// generic parameter of [`Collection`](../struct.Collection.html) instead of [`bson::Document`] can
+/// reduce the amount of time the driver and your application spends serializing and deserializing
+/// BSON, which can also lead to increased performance.
 ///
 /// ## TCP Keepalive
 /// TCP keepalive is enabled by default with ``tcp_keepalive_time`` set to 120 seconds. The

src/coll/mod.rs

@@ -1135,6 +1135,9 @@ where
 
     /// Inserts the data in `docs` into the collection.
     ///
+    /// Note that this method accepts both owned and borrowed values, so the input documents
+    /// do not need to be cloned in order to be passed in.
+    ///
     /// This operation will retry once upon failure if the connection and encountered error support
     /// retryability. See the documentation
     /// [here](https://docs.mongodb.com/manual/core/retryable-writes/) for more information on
@@ -1149,6 +1152,9 @@ where
 
     /// Inserts the data in `docs` into the collection using the provided `ClientSession`.
     ///
+    /// Note that this method accepts both owned and borrowed values, so the input documents
+    /// do not need to be cloned in order to be passed in.
+    ///
     /// This operation will retry once upon failure if the connection and encountered error support
     /// retryability. See the documentation
     /// [here](https://docs.mongodb.com/manual/core/retryable-writes/) for more information on
@@ -1187,6 +1193,9 @@ where
 
     /// Inserts `doc` into the collection.
     ///
+    /// Note that either an owned or borrowed value can be inserted here, so the input document
+    /// does not need to be cloned to be passed in.
+    ///
     /// This operation will retry once upon failure if the connection and encountered error support
     /// retryability. See the documentation
     /// [here](https://docs.mongodb.com/manual/core/retryable-writes/) for more information on
@@ -1201,6 +1210,9 @@ where
 
     /// Inserts `doc` into the collection using the provided `ClientSession`.
     ///
+    /// Note that either an owned or borrowed value can be inserted here, so the input document
+    /// does not need to be cloned to be passed in.
+    ///
     /// This operation will retry once upon failure if the connection and encountered error support
     /// retryability. See the documentation
     /// [here](https://docs.mongodb.com/manual/core/retryable-writes/) for more information on