Rollup merge of #154461 - lms0806:issue_154452, r=Mark-Simulacrum

Edit the docs new_in() and with_capacity_in()

I have updated the documentation for new_in().

While reviewing the code, I noticed that the documentation for with_capacity_in() was also inaccurate, so I have corrected it.

Close rust-lang/rust#154452

library/alloc/src/boxed.rs

@@ -695,6 +695,15 @@ pub fn try_new_zeroed_in(alloc: A) -> Result<Box<mem::MaybeUninit<T>, A>, AllocE
     /// does the same as <code>[Box::into_pin]\([Box::new_in]\(x, alloc))</code>. Consider using
     /// [`into_pin`](Box::into_pin) if you already have a `Box<T, A>`, or if you want to
     /// construct a (pinned) `Box` in a different way than with [`Box::new_in`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(allocator_api)]
+    /// use std::alloc::System;
+    ///
+    /// let x = Box::pin_in(1, System);
+    /// ```
     #[cfg(not(no_global_oom_handling))]
     #[unstable(feature = "allocator_api", issue = "32838")]
     #[must_use]

library/alloc/src/collections/binary_heap/mod.rs

@@ -549,8 +549,8 @@ impl<T, A: Allocator> BinaryHeap<T, A> {
     ///
     /// use std::alloc::System;
     /// use std::collections::BinaryHeap;
-    /// let mut heap = BinaryHeap::new_in(System);
-    /// heap.push(4);
+    ///
+    /// let heap : BinaryHeap<i32, System> = BinaryHeap::new_in(System);
     /// ```
     #[unstable(feature = "allocator_api", issue = "32838")]
     #[must_use]
@@ -573,8 +573,8 @@ pub const fn new_in(alloc: A) -> BinaryHeap<T, A> {
     ///
     /// use std::alloc::System;
     /// use std::collections::BinaryHeap;
-    /// let mut heap = BinaryHeap::with_capacity_in(10, System);
-    /// heap.push(4);
+    ///
+    /// let heap: BinaryHeap<i32, System> = BinaryHeap::with_capacity_in(10, System);
     /// ```
     #[unstable(feature = "allocator_api", issue = "32838")]
     #[must_use]

library/alloc/src/collections/btree/map.rs

@@ -684,13 +684,11 @@ pub fn clear(&mut self) {
     /// ```
     /// # #![feature(allocator_api)]
     /// # #![feature(btreemap_alloc)]
+    ///
     /// use std::collections::BTreeMap;
     /// use std::alloc::Global;
     ///
-    /// let mut map = BTreeMap::new_in(Global);
-    ///
-    /// // entries can now be inserted into the empty map
-    /// map.insert(1, "a");
+    /// let map: BTreeMap<i32, i32> = BTreeMap::new_in(Global);
     /// ```
     #[unstable(feature = "btreemap_alloc", issue = "32838")]
     #[must_use]

library/alloc/src/collections/btree/set.rs

@@ -355,10 +355,11 @@ impl<T, A: Allocator + Clone> BTreeSet<T, A> {
     /// # #![allow(unused_mut)]
     /// # #![feature(allocator_api)]
     /// # #![feature(btreemap_alloc)]
+    ///
     /// use std::collections::BTreeSet;
     /// use std::alloc::Global;
     ///
-    /// let mut set: BTreeSet<i32> = BTreeSet::new_in(Global);
+    /// let set: BTreeSet<i32> = BTreeSet::new_in(Global);
     /// ```
     #[unstable(feature = "btreemap_alloc", issue = "32838")]
     #[must_use]

library/alloc/src/collections/linked_list.rs

@@ -509,7 +509,7 @@ impl<T, A: Allocator> LinkedList<T, A> {
     /// use std::alloc::System;
     /// use std::collections::LinkedList;
     ///
-    /// let list: LinkedList<u32, _> = LinkedList::new_in(System);
+    /// let list: LinkedList<i32, System> = LinkedList::new_in(System);
     /// ```
     #[inline]
     #[unstable(feature = "allocator_api", issue = "32838")]

library/alloc/src/collections/vec_deque/mod.rs

@@ -790,7 +790,7 @@ pub const fn new() -> VecDeque<T> {
     /// ```
     /// use std::collections::VecDeque;
     ///
-    /// let deque: VecDeque<u32> = VecDeque::with_capacity(10);
+    /// let deque: VecDeque<i32> = VecDeque::with_capacity(10);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -830,9 +830,12 @@ impl<T, A: Allocator> VecDeque<T, A> {
     /// # Examples
     ///
     /// ```
-    /// use std::collections::VecDeque;
+    /// # #![feature(allocator_api)]
     ///
-    /// let deque: VecDeque<u32> = VecDeque::new();
+    /// use std::collections::VecDeque;
+    /// use std::alloc::Global;
+    ///
+    /// let deque: VecDeque<i32> = VecDeque::new_in(Global);
     /// ```
     #[inline]
     #[unstable(feature = "allocator_api", issue = "32838")]
@@ -845,9 +848,12 @@ pub const fn new_in(alloc: A) -> VecDeque<T, A> {
     /// # Examples
     ///
     /// ```
-    /// use std::collections::VecDeque;
+    /// # #![feature(allocator_api)]
     ///
-    /// let deque: VecDeque<u32> = VecDeque::with_capacity(10);
+    /// use std::collections::VecDeque;
+    /// use std::alloc::Global;
+    ///
+    /// let deque: VecDeque<i32> = VecDeque::with_capacity_in(10, Global);
     /// ```
     #[unstable(feature = "allocator_api", issue = "32838")]
     pub fn with_capacity_in(capacity: usize, alloc: A) -> VecDeque<T, A> {

library/alloc/src/rc.rs

@@ -737,6 +737,7 @@ impl<T, A: Allocator> Rc<T, A> {
     ///
     /// ```
     /// #![feature(allocator_api)]
+    ///
     /// use std::rc::Rc;
     /// use std::alloc::System;
     ///

library/alloc/src/vec/mod.rs

@@ -1062,8 +1062,7 @@ impl<T, A: Allocator> Vec<T, A> {
     ///
     /// use std::alloc::System;
     ///
-    /// # #[allow(unused_mut)]
-    /// let mut vec: Vec<i32, _> = Vec::new_in(System);
+    /// let vec: Vec<i32, System> = Vec::new_in(System);
     /// ```
     #[inline]
     #[unstable(feature = "allocator_api", issue = "32838")]

library/std/src/collections/hash/map.rs

@@ -301,8 +301,11 @@ impl<K, V, A: Allocator> HashMap<K, V, RandomState, A> {
     /// # Examples
     ///
     /// ```
+    /// # #![feature(allocator_api)]
     /// use std::collections::HashMap;
-    /// let mut map: HashMap<&str, i32> = HashMap::new();
+    /// use std::alloc::Global;
+    ///
+    /// let map: HashMap<i32, i32> = HashMap::new_in(Global);
     /// ```
     #[inline]
     #[must_use]
@@ -321,8 +324,11 @@ pub fn new_in(alloc: A) -> Self {
     /// # Examples
     ///
     /// ```
+    /// # #![feature(allocator_api)]
     /// use std::collections::HashMap;
-    /// let mut map: HashMap<&str, i32> = HashMap::with_capacity(10);
+    /// use std::alloc::Global;
+    ///
+    /// let map: HashMap<i32, i32> = HashMap::with_capacity_in(10, Global);
     /// ```
     #[inline]
     #[must_use]
@@ -410,6 +416,18 @@ impl<K, V, S, A: Allocator> HashMap<K, V, S, A> {
     ///
     /// The `hash_builder` passed should implement the [`BuildHasher`] trait for
     /// the `HashMap` to be useful, see its documentation for details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(allocator_api)]
+    /// use std::alloc::Global;
+    /// use std::collections::HashMap;
+    /// use std::hash::RandomState;
+    ///
+    /// let s = RandomState::new();
+    /// let map: HashMap<i32, i32> = HashMap::with_hasher_in(s, Global);
+    /// ```
     #[inline]
     #[must_use]
     #[unstable(feature = "allocator_api", issue = "32838")]
@@ -432,6 +450,17 @@ pub fn with_hasher_in(hash_builder: S, alloc: A) -> Self {
     /// The `hasher` passed should implement the [`BuildHasher`] trait for
     /// the `HashMap` to be useful, see its documentation for details.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(allocator_api)]
+    /// use std::alloc::Global;
+    /// use std::collections::HashMap;
+    /// use std::hash::RandomState;
+    ///
+    /// let s = RandomState::new();
+    /// let map: HashMap<i32, i32> = HashMap::with_capacity_and_hasher_in(10, s, Global);
+    /// ```
     #[inline]
     #[must_use]
     #[unstable(feature = "allocator_api", issue = "32838")]

library/std/src/collections/hash/set.rs

@@ -176,6 +176,15 @@ impl<T, A: Allocator> HashSet<T, RandomState, A> {
     ///
     /// The hash set is initially created with a capacity of 0, so it will not allocate until it
     /// is first inserted into.
+    /// # Examples
+    ///
+    /// ```
+    /// # #![feature(allocator_api)]
+    /// use std::alloc::Global;
+    /// use std::collections::HashSet;
+    ///
+    /// let set: HashSet<i32> = HashSet::new_in(Global);
+    /// ```
     #[inline]
     #[must_use]
     #[unstable(feature = "allocator_api", issue = "32838")]
@@ -192,9 +201,11 @@ pub fn new_in(alloc: A) -> HashSet<T, RandomState, A> {
     /// # Examples
     ///
     /// ```
+    /// # #![feature(allocator_api)]
     /// use std::collections::HashSet;
-    /// let set: HashSet<i32> = HashSet::with_capacity(10);
-    /// assert!(set.capacity() >= 10);
+    /// use std::alloc::Global;
+    ///
+    /// let set: HashSet<i32> = HashSet::with_capacity_in(10, Global);
     /// ```
     #[inline]
     #[must_use]
@@ -282,6 +293,18 @@ impl<T, S, A: Allocator> HashSet<T, S, A> {
     ///
     /// The `hash_builder` passed should implement the [`BuildHasher`] trait for
     /// the `HashSet` to be useful, see its documentation for details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #![feature(allocator_api)]
+    /// use std::alloc::Global;
+    /// use std::collections::HashSet;
+    /// use std::hash::RandomState;
+    ///
+    /// let s = RandomState::new();
+    /// let set: HashSet<i32> = HashSet::with_hasher_in(s, Global);
+    /// ```
     #[inline]
     #[must_use]
     #[unstable(feature = "allocator_api", issue = "32838")]
@@ -303,6 +326,18 @@ pub fn with_hasher_in(hasher: S, alloc: A) -> HashSet<T, S, A> {
     ///
     /// The `hash_builder` passed should implement the [`BuildHasher`] trait for
     /// the `HashSet` to be useful, see its documentation for details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #![feature(allocator_api)]
+    /// use std::alloc::Global;
+    /// use std::collections::HashSet;
+    /// use std::hash::RandomState;
+    ///
+    /// let s = RandomState::new();
+    /// let set: HashSet<i32> = HashSet::with_capacity_and_hasher_in(10, s, Global);
+    /// ```
     #[inline]
     #[must_use]
     #[unstable(feature = "allocator_api", issue = "32838")]