Rollup merge of #148662 - leftmostcat:document-isize-limit, r=joboet

alloc: Document panics when allocations will exceed max

Document panics in `String` and `Vec` due to capacity overflowing `isize::MAX`. Correct outdated claims of `usize::MAX` limit.

Fixes https://github.com/rust-lang/rust/issues/148598.

Ping `@lolbinarycat`

library/alloc/src/string.rs

@@ -454,6 +454,10 @@ pub const fn new() -> String {
     ///
     /// [`new`]: String::new
     ///
+    /// # Panics
+    ///
+    /// Panics if the capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1079,6 +1083,10 @@ pub const fn as_mut_str(&mut self) -> &mut str {
 
     /// Appends a given string slice onto the end of this `String`.
     ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1101,8 +1109,9 @@ pub fn push_str(&mut self, string: &str) {
     ///
     /// # Panics
     ///
-    /// Panics if the range has `start_bound > end_bound`, or, if the range is
-    /// bounded on either end and does not lie on a [`char`] boundary.
+    /// Panics if the range has `start_bound > end_bound`, if the range is
+    /// bounded on either end and does not lie on a [`char`] boundary, or if the
+    /// new capacity exceeds `isize::MAX` bytes.
     ///
     /// # Examples
     ///
@@ -1158,7 +1167,7 @@ pub const fn capacity(&self) -> usize {
     ///
     /// # Panics
     ///
-    /// Panics if the new capacity overflows [`usize`].
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
     ///
     /// # Examples
     ///
@@ -1208,7 +1217,7 @@ pub fn reserve(&mut self, additional: usize) {
     ///
     /// # Panics
     ///
-    /// Panics if the new capacity overflows [`usize`].
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
     ///
     /// # Examples
     ///
@@ -1372,6 +1381,10 @@ pub fn shrink_to(&mut self, min_capacity: usize) {
 
     /// Appends the given [`char`] to the end of this `String`.
     ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```

library/alloc/src/vec/mod.rs

@@ -3340,6 +3340,10 @@ pub fn resize(&mut self, new_len: usize, value: T) {
     /// except that it also works with slice elements that are Clone but not Copy.
     /// If Rust gets specialization this function may be deprecated.
     ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```
@@ -3361,8 +3365,9 @@ pub fn extend_from_slice(&mut self, other: &[T]) {
     ///
     /// # Panics
     ///
-    /// Panics if starting index is greater than the end index
-    /// or if the index is greater than the length of the vector.
+    /// Panics if starting index is greater than the end index, if the index is
+    /// greater than the length of the vector, or if the new capacity exceeds
+    /// `isize::MAX` _bytes_.
     ///
     /// # Examples
     ///