docs(allocator): extend doc comments for Vec and RawVec

Author: overlookmotel

crates/oxc_allocator/src/vec2/mod.rs

@@ -905,9 +905,9 @@ impl<'a, T: 'a, A: Alloc> Vec<'a, T, A> {
     /// greater than or equal to `self.len() + additional`. Does nothing if
     /// capacity is already sufficient.
     ///
-    /// # Panics
+    /// # Errors
     ///
-    /// Panics if the new capacity overflows `u32`.
+    /// Returns `Err(AllocError)` if unable to reserve requested space in the `Vec`.
     ///
     /// # Examples
     ///
@@ -932,9 +932,9 @@ impl<'a, T: 'a, A: Alloc> Vec<'a, T, A> {
     /// requests. Therefore capacity can not be relied upon to be precisely
     /// minimal. Prefer `try_reserve` if future insertions are expected.
     ///
-    /// # Panics
+    /// # Errors
     ///
-    /// Panics if the new capacity overflows `u32`.
+    /// Returns `Err(AllocError)` if unable to reserve requested space in the `Vec`.
     ///
     /// # Examples
     ///
@@ -1834,6 +1834,7 @@ impl<'a, T: 'a, A: Alloc> Vec<'a, T, A> {
     /// assert_eq!(vec2, [2, 3]);
     /// ```
     #[inline]
+    #[must_use]
     pub fn split_off(&mut self, at: usize) -> Self {
         assert!(at <= self.len_usize(), "`at` out of bounds");
 
@@ -2035,6 +2036,10 @@ impl<'a, T: 'a + Copy, A: Alloc> Vec<'a, T, A> {
     /// to precompute the total amount of space to reserve in advance. This reduces the potential
     /// maximum number of reallocations needed from one-per-slice to just one.
     ///
+    /// # Panics
+    ///
+    /// Panics if unable to reserve sufficient capacity in the `Vec` for the slices.
+    ///
     /// # Examples
     ///
     /// ```

crates/oxc_allocator/src/vec2/raw_vec.rs

@@ -85,6 +85,10 @@ impl<'a, T, A: Alloc> RawVec<'a, T, A> {
 
     /// Like `with_capacity` but parameterized over the choice of
     /// allocator for the returned RawVec.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `cap` is too large.
     #[inline]
     pub fn with_capacity_in(cap: usize, alloc: &'a A) -> Self {
         unsafe {
@@ -358,6 +362,10 @@ impl<'a, T, A: Alloc> RawVec<'a, T, A> {
     */
 
     /// The same as `reserve_exact`, but returns on errors instead of panicking or aborting.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err(AllocError)` if unable to reserve requested space in the `RawVec`.
     pub fn try_reserve_exact(&mut self, len: u32, additional: usize) -> Result<(), AllocError> {
         if self.needs_to_grow(len, additional) {
             self.grow_exact(len, additional)?
@@ -394,6 +402,10 @@ impl<'a, T, A: Alloc> RawVec<'a, T, A> {
     }
 
     /// The same as `reserve`, but returns on errors instead of panicking or aborting.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err(AllocError)` if unable to reserve requested space in the `RawVec`.
     pub fn try_reserve(&mut self, len: u32, additional: usize) -> Result<(), AllocError> {
         if self.needs_to_grow(len, additional) {
             self.grow_amortized(len, additional)?;
@@ -756,6 +768,10 @@ impl<T, A: Alloc> RawVec<'_, T, A> {
 
 impl<T, A: Alloc> RawVec<'_, T, A> {
     /// Frees the memory owned by the RawVec *without* trying to Drop its contents.
+    ///
+    /// # SAFETY
+    ///
+    /// Not sure what safety invariants of this method are! TODO
     pub unsafe fn dealloc_buffer(&mut self) {
         let elem_size = mem::size_of::<T>();
         if elem_size != 0 {