Auto merge of #31148 - steveklabnik:rollup, r=steveklabnik

- Successful merges: #30997, #31019, #31031, #31035, #31045, #31050, #31054, #31055, #31061, #31088, #31090, #31111, #31113, #31128, #31130, #31136, #31145, #31146
- Failed merges: #30932

4 files changed, 34 insertions, 7 deletions

diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index e43101b7c9d..43bf86a0039 100644
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -272,6 +272,35 @@ fn test_resize_policy() {
 /// }
 /// ```
 ///
+/// `HashMap` also implements an [`Entry API`](#method.entry), which allows
+/// for more complex methods of getting, setting, updating and removing keys and
+/// their values:
+///
+/// ```
+/// use std::collections::HashMap;
+///
+/// // type inference lets us omit an explicit type signature (which
+/// // would be `HashMap<&str, u8>` in this example).
+/// let mut player_stats = HashMap::new();
+///
+/// fn random_stat_buff() -> u8 {
+///   // could actually return some random value here - let's just return
+///   // some fixed value for now
+///   42
+/// }
+///
+/// // insert a key only if it doesn't already exist
+/// player_stats.entry("health").or_insert(100);
+///
+/// // insert a key using a function that provides a new value only if it
+/// // doesn't already exist
+/// player_stats.entry("defence").or_insert_with(random_stat_buff);
+///
+/// // update a key, guarding against the key possibly not being set
+/// let stat = player_stats.entry("attack").or_insert(100);
+/// *stat += random_stat_buff();
+/// ```
+///
 /// The easiest way to use `HashMap` with a custom type as key is to derive `Eq` and `Hash`.
 /// We must also derive `PartialEq`.
 ///
diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs
index d6aa746f4cb..9d505607a60 100644
--- a/src/libstd/ffi/c_str.rs
+++ b/src/libstd/ffi/c_str.rs
@@ -407,7 +407,6 @@ impl CStr {
     /// # fn main() {
     /// use std::ffi::CStr;
     /// use std::os::raw::c_char;
-    /// use std::str;
     ///
     /// extern {
     ///     fn my_string() -> *const c_char;
@@ -415,8 +414,7 @@ impl CStr {
     ///
     /// unsafe {
     ///     let slice = CStr::from_ptr(my_string());
-    ///     println!("string returned: {}",
-    ///              str::from_utf8(slice.to_bytes()).unwrap());
+    ///     println!("string returned: {}", slice.to_str().unwrap());
     /// }
     /// # }
     /// ```
diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index 414a0ebd11f..187a1797dac 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -414,7 +414,7 @@ impl OpenOptions {
     /// This option, when true, will indicate that the file should be
     /// `write`-able if opened.
     ///
-    /// If a file already exist, any write calls on the file will overwrite its
+    /// If the file already exists, any write calls on it will overwrite its
     /// contents, without truncating it.
     ///
     /// # Examples
@@ -487,8 +487,8 @@ impl OpenOptions {
     /// This option indicates whether a new file will be created if the file
     /// does not yet already exist.
     ///
-    /// The file must be opened with write or append access in order to create
-    /// a new file.
+    /// In order for the file to be created, `write` or `append` access must
+    /// be used.
     ///
     /// # Examples
     ///
diff --git a/src/libstd/sync/semaphore.rs b/src/libstd/sync/semaphore.rs
index 8f08c840c21..ac5ce298c5c 100644
--- a/src/libstd/sync/semaphore.rs
+++ b/src/libstd/sync/semaphore.rs
@@ -13,7 +13,7 @@
                       of resources is currently unclear",
             issue = "27798")]
 #![rustc_deprecated(since = "1.7.0",
-                    reason = "easily confused with system sempahores and not \
+                    reason = "easily confused with system semaphores and not \
                               used enough to pull its weight")]
 #![allow(deprecated)]