docs(semantic): fix and reformat doc comments (#8652)

Update doc comment for `TempUnresolvedReferences` which was out of date. Reformat other comments.

crates/oxc_semantic/src/unresolved_stack.rs

@@ -4,7 +4,8 @@ use rustc_hash::FxHashMap;
 use oxc_span::Atom;
 use oxc_syntax::reference::ReferenceId;
 
-/// The difference with Scope's `UnresolvedReferences` is that this type uses Atom as the key. its clone is very cheap!
+/// Unlike `ScopeTree`'s `UnresolvedReferences`, this type uses `Atom` as the key,
+/// and uses a heap-allocated hashmap (not arena-allocated)
 type TempUnresolvedReferences<'a> = FxHashMap<Atom<'a>, Vec<ReferenceId>>;
 
 // Stack used to accumulate unresolved refs while traversing scopes.
@@ -21,16 +22,19 @@ pub(crate) struct UnresolvedReferencesStack<'a> {
 }
 
 impl<'a> UnresolvedReferencesStack<'a> {
-    // Initial scope depth.
-    // Start on 1 (`Program` scope depth).
-    // SAFETY: Must be >= 1 to ensure soundness of `current_and_parent_mut`.
+    /// Initial scope depth.
+    /// Start on 1 (`Program` scope depth).
+    /// SAFETY: Must be >= 1 to ensure soundness of `current_and_parent_mut`.
     const INITIAL_DEPTH: usize = 1;
-    // Most programs will have at least 1 place where scope depth reaches 16,
-    // so initialize `stack` with this length, to reduce reallocations as it grows.
-    // This is just an estimate of a good initial size, but certainly better than
-    // `Vec`'s default initial capacity of 4.
-    // SAFETY: Must be >= 2 to ensure soundness of `current_and_parent_mut`.
+
+    /// Most programs will have at least 1 place where scope depth reaches 16,
+    /// so initialize `stack` with this length, to reduce reallocations as it grows.
+    /// This is just an estimate of a good initial size, but certainly better than
+    /// `Vec`'s default initial capacity of 4.
+    /// SAFETY: Must be >= 2 to ensure soundness of `current_and_parent_mut`.
     const INITIAL_SIZE: usize = 16;
+
+    /// Assert invariant
     #[allow(clippy::assertions_on_constants)]
     const _SIZE_CHECK: () = assert!(Self::INITIAL_SIZE > Self::INITIAL_DEPTH);