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,14 +1,13 @@
//! Test-only tracing capture: count events whose `message` starts with a
//! known prefix.
//! Count tracing events whose `message` starts with a known prefix.
//!
//! Producers should export the exact log-line prefixes as `pub const`s next
//! to the `tracing::debug!` call sites (e.g. `kigi_hunk_tracker`'s
//! `REFRESH_SCAN_LOG_PREFIX`) so tests never duplicate the strings.
//! Producers should export exact prefixes as `pub const`s next to the
//! `tracing::debug!` site (e.g. `REFRESH_SCAN_LOG_PREFIX`) so tests never
//! duplicate the strings.
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
/// Extracts the formatted `message` field of one event.
/// Pulls the formatted `message` field off one event.
#[derive(Default)]
struct MessageVisitor(String);
@@ -20,8 +19,8 @@ impl tracing::field::Visit for MessageVisitor {
}
}
/// A `tracing_subscriber::Layer` counting, per registered prefix, the events
/// whose `message` starts with it. Clones share the counts.
/// Layer that counts, per registered prefix, events whose `message` starts
/// with it. Clones share the same counters.
#[derive(Clone)]
pub struct MessagePrefixCounter {
counters: Arc<Vec<(&'static str, AtomicUsize)>>,
@@ -34,8 +33,7 @@ impl MessagePrefixCounter {
}
}
/// Events counted so far for `prefix`. Panics on a prefix that was never
/// registered — that is a bug in the test, not a zero count.
/// Count for `prefix`. Panics if `prefix` was never registered.
pub fn count(&self, prefix: &str) -> usize {
self.counters
.iter()
@@ -62,9 +60,9 @@ impl<S: tracing::Subscriber> tracing_subscriber::Layer<S> for MessagePrefixCount
}
}
/// Install a **thread-scoped** default subscriber counting `prefixes`; hold
/// the guard for the test's lifetime. Only observes events emitted on the
/// current thread — tasks under test must run on a current-thread runtime.
/// Thread-scoped default subscriber counting `prefixes`. Hold the guard for
/// the test lifetime. Only sees events on the current thread — use a
/// current-thread runtime for the subject under test.
pub fn install_prefix_counter_thread(
prefixes: &[&'static str],
) -> (tracing::subscriber::DefaultGuard, MessagePrefixCounter) {
@@ -74,12 +72,10 @@ pub fn install_prefix_counter_thread(
(tracing::subscriber::set_default(subscriber), counter)
}
/// Install the **process-global** subscriber counting `prefixes` — for tests
/// whose subject spawns its own threads/runtimes. Panics if a global
/// subscriber already exists: the test binary must own it.
/// Process-global subscriber counting `prefixes` — for subjects that spawn
/// their own threads/runtimes. Panics if a global subscriber already exists.
///
/// `stderr_env_filter` additionally tees formatted logs matching the given
/// `EnvFilter` directive to stderr (local debugging).
/// `stderr_env_filter` optionally tees matching formatted logs to stderr.
pub fn install_prefix_counter_global(
prefixes: &[&'static str],
stderr_env_filter: Option<&str>,