Clean up comments: remove redundant/stale remarks, fix CPython refere…

…nces
RustPython · youknowone · Mar 4, 2026 · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026
commit 22df0c60a0849bd332c921c1be574aa0811eb07b
diff --git a/crates/common/src/lock.rs b/crates/common/src/lock.rs
@@ -20,10 +20,9 @@ cfg_if::cfg_if! {
     }
 }
 
-// LazyLock: thread-safe lazy initialization for `static` items.
-// In non-threading mode with std, use std::sync::LazyLock for safety
-// (Rust test runner uses parallel threads even without the threading feature).
-// Without std, use a LazyCell wrapper (truly single-threaded environments only).
+// LazyLock: uses std::sync::LazyLock when std is available (even without
+// threading, because Rust test runner uses parallel threads).
+// Without std, uses a LazyCell wrapper (truly single-threaded only).
 cfg_if::cfg_if! {
     if #[cfg(any(feature = "threading", feature = "std"))] {
         pub use std::sync::LazyLock;

diff --git a/crates/vm/src/datastack.rs b/crates/vm/src/datastack.rs
@@ -1,16 +1,14 @@
-/// Thread data stack for interpreter frames.
+/// Thread data stack for interpreter frames (`_PyStackChunk` /
+/// `tstate->datastack_*`).
 ///
 /// A linked list of chunks providing bump allocation for frame-local data
-/// (localsplus arrays). Mirrors `_PyStackChunk` / `tstate->datastack_*`
-/// from CPython.
-///
-/// Normal function calls allocate from the data stack via `push()` (pointer
-/// bump).  Generators and coroutines use heap-allocated storage instead.
+/// (localsplus arrays).  Normal function calls allocate via `push()`
+/// (pointer bump).  Generators and coroutines use heap-allocated storage.
 use alloc::alloc::{alloc, dealloc};
 use core::alloc::Layout;
 use core::ptr;
 
-/// Minimum chunk size in bytes (16 KB, matching CPython `_PY_DATA_STACK_CHUNK_SIZE`).
+/// Minimum chunk size in bytes (`_PY_DATA_STACK_CHUNK_SIZE`).
 const MIN_CHUNK_SIZE: usize = 16 * 1024;
 
 /// Extra headroom (in bytes) to avoid allocating a new chunk for the next
@@ -66,7 +64,7 @@ impl DataStack {
         let top = unsafe { (*chunk).data_start() };
         let limit = unsafe { (*chunk).data_limit() };
         // Skip one ALIGN-sized slot in the root chunk so that `pop()` never
-        // frees it (same trick as CPython's `push_chunk`).
+        // frees it (`push_chunk` convention).
         let top = unsafe { top.add(ALIGN) };
         Self { chunk, top, limit }
     }

diff --git a/crates/vm/src/frame.rs b/crates/vm/src/frame.rs
@@ -66,9 +66,6 @@ enum UnwindReason {
     Raising { exception: PyBaseExceptionRef },
 }
 
-// FrameState fields are stored directly on Frame as UnsafeCell.
-// See Frame.localsplus, Frame.cells_frees, Frame.prev_line.
-
 /// Tracks who owns a frame.
 // = `_PyFrameOwner`
 #[repr(i8)]
@@ -203,7 +200,6 @@ impl LocalsPlus {
     fn materialize_to_heap(&mut self) -> Option<*mut u8> {
         if let LocalsPlusData::DataStack { ptr, capacity } = &self.data {
             let base = *ptr as *mut u8;
-            // Copy all data to a heap allocation (preserves locals for tracebacks).
             let heap_data = unsafe { core::slice::from_raw_parts(*ptr, *capacity) }
                 .to_vec()
                 .into_boxed_slice();
@@ -461,7 +457,6 @@ impl ExactSizeIterator for LocalsPlusStackDrain<'_> {}
 
 impl Drop for LocalsPlusStackDrain<'_> {
     fn drop(&mut self) {
-        // Drop any remaining elements that weren't consumed.
         while self.current < self.end {
             let idx = self.localsplus.nlocalsplus as usize + self.current;
             let data = self.localsplus.data_as_mut_slice();
@@ -671,7 +666,6 @@ impl Frame {
                 .chain(closure.iter().cloned())
                 .collect();
 
-        // Create unified localsplus: varnames + cellvars + freevars + stack
         let nlocalsplus = nlocals
             .checked_add(num_cells)
             .and_then(|v| v.checked_add(nfrees))
@@ -1001,8 +995,8 @@ impl Py<Frame> {
     }
 }
 
-/// An executing frame; essentially just a struct to combine the immutable data outside the mutex
-/// with the mutable data inside
+/// An executing frame; borrows mutable frame-internal data for the duration
+/// of bytecode execution.
 struct ExecutingFrame<'a> {
     code: &'a PyRef<PyCode>,
     localsplus: &'a mut LocalsPlus,