Feat: WIP terse code documentation

crates/forth/src/words/compile.rs

@@ -1,3 +1,5 @@
+//! Word-to-Op translation: maps Forth word names to compiled instructions.
+
 use std::sync::Arc;
 
 use crate::ops::Op;

crates/forth/src/words/core.rs

@@ -1,6 +1,6 @@
-use super::{Word, WordCompile::*};
+//! Word metadata for core language primitives (stack, arithmetic, logic, variables, definitions).
 
-// Stack, Arithmetic, Comparison, Logic, Control, Variables, Definitions
+use super::{Word, WordCompile::*};
 pub(super) const WORDS: &[Word] = &[
     // Stack manipulation
     Word {

crates/forth/src/words/effects.rs

@@ -1,6 +1,6 @@
-use super::{Word, WordCompile::*};
+//! Word metadata for audio effect parameters (filter, envelope, reverb, delay, lo-fi, stereo, mod FX).
 
-// Filter, Envelope, Reverb, Delay, Lo-fi, Stereo, Mod FX
+use super::{Word, WordCompile::*};
 pub(super) const WORDS: &[Word] = &[
     // Envelope
     Word {

crates/forth/src/words/midi.rs

@@ -1,6 +1,7 @@
+//! MIDI word definitions: channel, CC, pitch bend, transport, and device routing.
+
 use super::{Word, WordCompile::*};
 
-// MIDI
 pub(super) const WORDS: &[Word] = &[
     Word {
         name: "chan",

crates/forth/src/words/mod.rs

@@ -1,3 +1,5 @@
+//! Built-in word definitions and lookup for the Forth VM.
+
 mod compile;
 mod core;
 mod effects;
@@ -11,6 +13,7 @@ use std::sync::LazyLock;
 
 pub(crate) use compile::compile_word;
 
+/// How a word is compiled into ops.
 #[derive(Clone, Copy)]
 pub enum WordCompile {
     Simple,
@@ -19,6 +22,7 @@ pub enum WordCompile {
     Probability(f64),
 }
 
+/// Metadata for a built-in Forth word.
 #[derive(Clone, Copy)]
 pub struct Word {
     pub name: &'static str,
@@ -31,6 +35,7 @@ pub struct Word {
     pub varargs: bool,
 }
 
+/// All built-in words, aggregated from every category module.
 pub static WORDS: LazyLock<Vec<Word>> = LazyLock::new(|| {
     let mut words = Vec::new();
     words.extend_from_slice(self::core::WORDS);
@@ -42,6 +47,7 @@ pub static WORDS: LazyLock<Vec<Word>> = LazyLock::new(|| {
     words
 });
 
+/// Index mapping word names and aliases to their definitions.
 static WORD_MAP: LazyLock<HashMap<&'static str, &'static Word>> = LazyLock::new(|| {
     let mut map = HashMap::with_capacity(WORDS.len() * 2);
     for word in WORDS.iter() {
@@ -53,6 +59,7 @@ static WORD_MAP: LazyLock<HashMap<&'static str, &'static Word>> = LazyLock::new(
     map
 });
 
+/// Find a word by name or alias.
 pub fn lookup_word(name: &str) -> Option<&'static Word> {
     WORD_MAP.get(name).copied()
 }

crates/forth/src/words/music.rs

@@ -1,6 +1,7 @@
+//! Word definitions for music theory, harmony, and chord construction.
+
 use super::{Word, WordCompile::*};
 
-// Music, Chord
 pub(super) const WORDS: &[Word] = &[
     // Music
     Word {

crates/forth/src/words/sequencing.rs

@@ -1,6 +1,7 @@
+//! Word metadata for sequencing: probability, timing, context queries, generators.
+
 use super::{Word, WordCompile::*};
 
-// Time, Context, Probability, Generator, Desktop
 pub(super) const WORDS: &[Word] = &[
     // Probability
     Word {

crates/forth/src/words/sound.rs

@@ -1,6 +1,7 @@
+//! Word metadata for sound commands, sample/oscillator params, FM, modulation, and LFO.
+
 use super::{Word, WordCompile::*};
 
-// Sound, Oscillator, Sample, Wavetable, FM, Modulation, LFO
 pub(super) const WORDS: &[Word] = &[
     // Sound
     Word {