Example from the scheduler docs: “We use a lock-free queue here, not because of raw speed, but because holding a spinlock across a timer interrupt would violate Rust’s Send/Sync guarantees. Here’s the proof…” That’s gold. That’s the kind of insight you usually only get from a hallway conversation at a conference. Kernel docs are notoriously bad at explaining page tables, GDTs, or frame allocators. RCore docs embed visualizations directly into the markdown. Early chapters use ASCII diagrams for quick terminal reading, while later modules link to SVG renders of the memory map.
The next time you find yourself squinting at a bare #[repr(C)] struct with no explanation, remember: it doesn’t have to be this way. Good docs aren’t a luxury. In systems programming, they’re a safety net. rcore docs
This sounds simple, but it’s revolutionary. You never feel like the docs and the code were written by different civilizations. Because RCore is written in Rust, the docs constantly ask: Why is this part safe? Why use a channel here instead of a raw spinlock? Each unsafe block is annotated with a doc comment explaining the invariants—not just for the compiler, but for the human trying to modify the kernel six months later. Example from the scheduler docs: “We use a
