From e544783a73d07aa34477b8e710535e2c36385b12 Mon Sep 17 00:00:00 2001
From: overlookmotel <theoverlookmotel@gmail.com>
Date: Mon, 20 Jan 2025 11:22:52 +0000
Subject: [PATCH] docs(allocator): reformat docs

---
 crates/oxc_allocator/src/boxed.rs    | 6 +++---
 crates/oxc_allocator/src/hash_map.rs | 2 +-
 crates/oxc_allocator/src/lib.rs      | 7 +++----
 crates/oxc_allocator/src/string.rs   | 7 +------
 crates/oxc_allocator/src/vec.rs      | 6 +-----
 5 files changed, 9 insertions(+), 19 deletions(-)

diff --git a/crates/oxc_allocator/src/boxed.rs b/crates/oxc_allocator/src/boxed.rs
index 003b493404d3af..02d6d41b443d28 100644
--- a/crates/oxc_allocator/src/boxed.rs
+++ b/crates/oxc_allocator/src/boxed.rs
@@ -19,7 +19,7 @@ use crate::Allocator;
 
 /// A `Box` without [`Drop`], which stores its data in the arena allocator.
 ///
-/// ## No `Drop`s
+/// # No `Drop`s
 ///
 /// Objects allocated into Oxc memory arenas are never [`Dropped`](Drop). Memory is released in bulk
 /// when the allocator is dropped, without dropping the individual objects in the arena.
@@ -35,7 +35,7 @@ impl<T> Box<'_, T> {
     /// Take ownership of the value stored in this [`Box`], consuming the box in
     /// the process.
     ///
-    /// ## Example
+    /// # Examples
     /// ```
     /// use oxc_allocator::{Allocator, Box};
     ///
@@ -64,7 +64,7 @@ impl<T> Box<'_, T> {
     /// Put a `value` into a memory arena and get back a [`Box`] with ownership
     /// to the allocation.
     ///
-    /// ## Example
+    /// # Examples
     /// ```
     /// use oxc_allocator::{Allocator, Box};
     ///
diff --git a/crates/oxc_allocator/src/hash_map.rs b/crates/oxc_allocator/src/hash_map.rs
index 094284968c74b0..125f2f91cdbe60 100644
--- a/crates/oxc_allocator/src/hash_map.rs
+++ b/crates/oxc_allocator/src/hash_map.rs
@@ -36,7 +36,7 @@ type FxHashMap<'alloc, K, V> = hashbrown::HashMap<K, V, FxBuildHasher, &'alloc B
 /// All APIs are the same, except create a [`HashMap`] with
 /// either [`new_in`](HashMap::new_in) or [`with_capacity_in`](HashMap::with_capacity_in).
 ///
-/// ## No `Drop`s
+/// # No `Drop`s
 ///
 /// Objects allocated into Oxc memory arenas are never [`Dropped`](Drop). Memory is released in bulk
 /// when the allocator is dropped, without dropping the individual objects in the arena.
diff --git a/crates/oxc_allocator/src/lib.rs b/crates/oxc_allocator/src/lib.rs
index 0e3396cb41eb82..265827cc3a07a2 100644
--- a/crates/oxc_allocator/src/lib.rs
+++ b/crates/oxc_allocator/src/lib.rs
@@ -94,7 +94,7 @@ impl Allocator {
     /// # Panics
     /// Panics if reserving space for `T` fails.
     ///
-    /// # Example
+    /// # Examples
     /// ```
     /// use oxc_allocator::Allocator;
     ///
@@ -120,7 +120,7 @@ impl Allocator {
     /// # Panics
     /// Panics if reserving space for the string fails.
     ///
-    /// # Example
+    /// # Examples
     /// ```
     /// use oxc_allocator::Allocator;
     /// let allocator = Allocator::default();
@@ -145,8 +145,7 @@ impl Allocator {
     /// If this arena has allocated multiple chunks to bump allocate into, then the excess chunks
     /// are returned to the global allocator.
     ///
-    /// ## Example
-    ///
+    /// # Examples
     /// ```
     /// use oxc_allocator::Allocator;
     ///
diff --git a/crates/oxc_allocator/src/string.rs b/crates/oxc_allocator/src/string.rs
index 90c7d8899249dc..796f2b3b509da7 100644
--- a/crates/oxc_allocator/src/string.rs
+++ b/crates/oxc_allocator/src/string.rs
@@ -63,7 +63,6 @@ impl<'alloc> String<'alloc> {
     /// Construct a new [`String`] from a string slice.
     ///
     /// # Examples
-    ///
     /// ```
     /// use oxc_allocator::{Allocator, String};
     ///
@@ -126,9 +125,6 @@ impl<'alloc> String<'alloc> {
     /// nothing else uses the pointer after calling this function.
     ///
     /// # Examples
-    ///
-    /// Basic usage:
-    ///
     /// ```
     /// use std::mem;
     /// use oxc_allocator::{Allocator, String};
@@ -163,8 +159,7 @@ impl<'alloc> String<'alloc> {
     /// Convert this `String<'alloc>` into an `&'alloc str`. This is analogous to
     /// [`std::string::String::into_boxed_str`].
     ///
-    /// # Example
-    ///
+    /// # Examples
     /// ```
     /// use oxc_allocator::{Allocator, String};
     ///
diff --git a/crates/oxc_allocator/src/vec.rs b/crates/oxc_allocator/src/vec.rs
index 9f476fbc2064a2..dc798bdf98e8dc 100644
--- a/crates/oxc_allocator/src/vec.rs
+++ b/crates/oxc_allocator/src/vec.rs
@@ -24,7 +24,7 @@ use crate::{Allocator, Box};
 
 /// A `Vec` without [`Drop`], which stores its data in the arena allocator.
 ///
-/// ## No `Drop`s
+/// # No `Drop`s
 ///
 /// Objects allocated into Oxc memory arenas are never [`Dropped`](Drop). Memory is released in bulk
 /// when the allocator is dropped, without dropping the individual objects in the arena.
@@ -48,7 +48,6 @@ impl<'alloc, T> Vec<'alloc, T> {
     /// The vector will not allocate until elements are pushed onto it.
     ///
     /// # Examples
-    ///
     /// ```
     /// use oxc_allocator::{Allocator, Vec};
     ///
@@ -84,7 +83,6 @@ impl<'alloc, T> Vec<'alloc, T> {
     /// Panics if the new capacity exceeds `isize::MAX` bytes.
     ///
     /// # Examples
-    ///
     /// ```
     /// use oxc_allocator::{Allocator, Vec};
     ///
@@ -147,7 +145,6 @@ impl<'alloc, T> Vec<'alloc, T> {
     /// on stack and then copying to arena.
     ///
     /// # Examples
-    ///
     /// ```
     /// use oxc_allocator::{Allocator, Vec};
     ///
@@ -178,7 +175,6 @@ impl<'alloc, T> Vec<'alloc, T> {
     /// The excess memory will be leaked in the arena (i.e. not reused by another allocation).
     ///
     /// # Examples
-    ///
     /// ```
     /// use oxc_allocator::{Allocator, Vec};
     ///