Merge pull request diesel-rs#3917 from greyblake/fix-doc-example-returning-does-not-preserve-order

Fix doc example to make it clear that ".returning()" does not preserve original order

Author: weiznich

diesel/src/query_builder/insert_statement/mod.rs

@@ -281,8 +281,12 @@ impl<T: QuerySource, U, Op> InsertStatement<T, U, Op> {
     /// let inserted_names = diesel::insert_into(users)
     ///     .values(&vec![name.eq("Timmy"), name.eq("Jimmy")])
     ///     .returning(name)
-    ///     .get_results(connection);
-    /// assert_eq!(Ok(vec!["Timmy".to_string(), "Jimmy".to_string()]), inserted_names);
+    ///     .get_results(connection)
+    ///     .unwrap();
+    /// // Note that the returned order is not guaranteed to be preserved
+    /// assert_eq!(inserted_names.len(), 2);
+    /// assert!(inserted_names.contains(&"Timmy".to_string()));
+    /// assert!(inserted_names.contains(&"Jimmy".to_string()));
     /// # }
     /// # #[cfg(not(feature = "postgres"))]
     /// # fn main() {}