docs(comments): rewrite comments across all crates to the guidelines

Sweep every first-party crate source (1956 .rs files) to the project comment
guidelines: delete redundant restatements, decorative banners, change
narration, and end-of-line comments; keep and tighten the crucial ones
(invariants, bug rationale, SAFETY blocks, ported-source attribution).

No functional code changed. Every edit is proven comment-only against the
prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a
separate doctest-fence check. Where removing a comment made rustfmt or clippy
want to re-lay-out adjacent code, the minimal triggering comment is restored so
code tokens stay byte-identical.

Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy
--workspace --all-targets (0 warnings).

Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for
these guidelines (flags banners, end-of-line comments, change narration, and
commented-out code).
This commit is contained in:
ZacharyZhang-NY committed 2026-07-23 16:55:39 -04:00
1 parent ff0fb56c67
commit a02b555e66
1458 files changed
+10729 -21750

No files matched your search

@@ -1,7 +1,6 @@
//! Shared event queue for the push path: producers enqueue out-of-band events;
//! readers drain the ones relevant to them at hook points. Internally
//! synchronized and `Arc`-shared (clones share one queue), mirroring
//! [`crate::buffer::InterjectionBuffer`].
//! Shared push-path event queue: producers enqueue; readers drain at hook
//! points. Internally synchronized and `Arc`-shared (clones share one queue),
//! matching [`crate::buffer::InterjectionBuffer`].
use std::sync::{Arc, Mutex, MutexGuard};
@@ -31,12 +30,11 @@ impl<E> EventQueue<E> {
}
}
/// Producer hook: record an event for later draining.
pub fn push(&self, event: E) {
self.lock().push(event);
}
/// Push, then drop the oldest events so at most `max` remain.
/// Push, then drop oldest entries so length stays ≤ `max`.
pub fn push_capped(&self, event: E, max: usize) {
let mut q = self.lock();
q.push(event);
@@ -54,8 +52,7 @@ impl<E> EventQueue<E> {
self.lock().is_empty()
}
/// Remove and return events matching `take`, retaining the rest. FIFO order
/// is preserved in both the returned and retained sets.
/// Remove matching events; keep the rest. Both sets stay FIFO.
pub fn drain_matching(&self, take: impl Fn(&E) -> bool) -> Vec<E> {
let mut q = self.lock();
let (matched, kept): (Vec<E>, Vec<E>) =
@@ -64,12 +61,10 @@ impl<E> EventQueue<E> {
matched
}
/// Remove and return all events, leaving the queue empty (FIFO order).
pub fn drain_all(&self) -> Vec<E> {
std::mem::take(&mut *self.lock())
}
/// Discard all events.
pub fn clear(&self) {
self.lock().clear();
}
@@ -80,7 +75,7 @@ impl<E> EventQueue<E> {
}
impl<E: Clone> EventQueue<E> {
/// Clone of the current events, for inspection without draining.
/// Snapshot without draining.
pub fn snapshot(&self) -> Vec<E> {
self.lock().clone()
}