Cagire/TODO.md

Rustdoc & Cleanup Review

Workflow

Strictly one file at a time, in list order. When the user says "review" (or similar), process the next unchecked file — never skip ahead, never batch.

1. Read the file.
2. Read any imports, callers, or sibling files needed to understand what the code does and how it fits in the codebase. Gathering context is encouraged.
3. Apply the changes described below.
4. cargo build to confirm nothing broke.
5. Check the file off in this list.
6. Stop. Wait for the user before moving to the next file.

What to do

1. Add //! module doc at the top if missing — one or two lines explaining what the module does and its role in the crate.
2. Add /// on public items (structs, enums, functions, traits, type aliases). Keep it to one line when possible. Document struct fields only when the name alone is not self-explanatory.
3. Light cleanup — remove dead code, fix misleading names, apply trivial simplifications. No behavior changes.
4. cargo build after each file to confirm nothing broke.

What NOT to do

• No comments on private internals unless truly obscure.
• No fluff ("This struct represents…"). Be direct.
• No feature changes, refactoring sprees, or reformatting of unrelated code.
• No over-commenting. If the code is clear, leave it alone.

Style

Sparse, english, imperative where possible. Match the tone of the existing codebase.

---

• build.rs
• crates/forth/src/compiler.rs
• crates/forth/src/lib.rs
• crates/forth/src/ops.rs
• crates/forth/src/theory/chords.rs
• crates/forth/src/theory/mod.rs
• crates/forth/src/theory/scales.rs
• crates/forth/src/types.rs
• crates/forth/src/vm.rs
• crates/forth/src/words/compile.rs
• crates/forth/src/words/core.rs
• crates/forth/src/words/effects.rs
• crates/forth/src/words/midi.rs
• crates/forth/src/words/mod.rs
• crates/forth/src/words/music.rs
• crates/forth/src/words/sequencing.rs
• crates/forth/src/words/sound.rs
• crates/markdown/src/highlighter.rs
• crates/markdown/src/lib.rs
• crates/markdown/src/parser.rs
• crates/markdown/src/theme.rs
• crates/project/src/file.rs
• crates/project/src/lib.rs
• crates/project/src/project.rs
• crates/project/src/share.rs
• crates/ratatui/src/category_list.rs
• crates/ratatui/src/confirm.rs
• crates/ratatui/src/editor.rs
• crates/ratatui/src/file_browser.rs
• crates/ratatui/src/hint_bar.rs
• crates/ratatui/src/lib.rs
• crates/ratatui/src/lissajous.rs
• crates/ratatui/src/list_select.rs
• crates/ratatui/src/modal.rs
• crates/ratatui/src/nav_minimap.rs
• crates/ratatui/src/props_form.rs
• crates/ratatui/src/sample_browser.rs
• crates/ratatui/src/scope.rs
• crates/ratatui/src/scroll_indicators.rs
• crates/ratatui/src/search_bar.rs
• crates/ratatui/src/section_header.rs
• crates/ratatui/src/sparkles.rs
• crates/ratatui/src/spectrum.rs
• crates/ratatui/src/text_input.rs
• crates/ratatui/src/theme/build.rs
• crates/ratatui/src/theme/catppuccin_latte.rs
• crates/ratatui/src/theme/catppuccin_mocha.rs
• crates/ratatui/src/theme/dracula.rs
• crates/ratatui/src/theme/eden.rs
• crates/ratatui/src/theme/ember.rs
• crates/ratatui/src/theme/everforest.rs
• crates/ratatui/src/theme/fairyfloss.rs
• crates/ratatui/src/theme/fauve.rs
• crates/ratatui/src/theme/georges.rs
• crates/ratatui/src/theme/gruvbox_dark.rs
• crates/ratatui/src/theme/hot_dog_stand.rs
• crates/ratatui/src/theme/iceberg.rs
• crates/ratatui/src/theme/jaipur.rs
• crates/ratatui/src/theme/kanagawa.rs
• crates/ratatui/src/theme/letz_light.rs
• crates/ratatui/src/theme/mod.rs
• crates/ratatui/src/theme/monochrome_black.rs
• crates/ratatui/src/theme/monochrome_white.rs
• crates/ratatui/src/theme/monokai.rs
• crates/ratatui/src/theme/nord.rs
• crates/ratatui/src/theme/palette.rs
• crates/ratatui/src/theme/pitch_black.rs
• crates/ratatui/src/theme/rose_pine.rs
• crates/ratatui/src/theme/tokyo_night.rs
• crates/ratatui/src/theme/transform.rs
• crates/ratatui/src/theme/tropicalia.rs
• crates/ratatui/src/vu_meter.rs
• crates/ratatui/src/waveform.rs
• plugins/baseview/src/clipboard.rs
• plugins/baseview/src/event.rs
• plugins/baseview/src/gl/macos.rs
• plugins/baseview/src/gl/mod.rs
• plugins/baseview/src/gl/win.rs
• plugins/baseview/src/gl/x11.rs
• plugins/baseview/src/gl/x11/errors.rs
• plugins/baseview/src/keyboard.rs
• plugins/baseview/src/lib.rs
• plugins/baseview/src/macos/keyboard.rs
• plugins/baseview/src/macos/mod.rs
• plugins/baseview/src/macos/view.rs
• plugins/baseview/src/macos/window.rs
• plugins/baseview/src/mouse_cursor.rs
• plugins/baseview/src/win/cursor.rs
• plugins/baseview/src/win/drop_target.rs
• plugins/baseview/src/win/hook.rs
• plugins/baseview/src/win/keyboard.rs
• plugins/baseview/src/win/mod.rs
• plugins/baseview/src/win/window.rs
• plugins/baseview/src/window_info.rs
• plugins/baseview/src/window_open_options.rs
• plugins/baseview/src/window.rs
• plugins/baseview/src/x11/cursor.rs
• plugins/baseview/src/x11/event_loop.rs
• plugins/baseview/src/x11/keyboard.rs
• plugins/baseview/src/x11/mod.rs
• plugins/baseview/src/x11/visual_info.rs
• plugins/baseview/src/x11/window.rs
• plugins/baseview/src/x11/xcb_connection.rs
• plugins/cagire-plugins/src/editor.rs
• plugins/cagire-plugins/src/lib.rs
• plugins/cagire-plugins/src/main.rs
• plugins/cagire-plugins/src/params.rs
• plugins/egui-baseview/src/lib.rs
• plugins/egui-baseview/src/renderer.rs
• plugins/egui-baseview/src/renderer/opengl.rs
• plugins/egui-baseview/src/renderer/opengl/renderer.rs
• plugins/egui-baseview/src/translate.rs
• plugins/egui-baseview/src/window.rs
• plugins/nih-plug-egui/src/editor.rs
• plugins/nih-plug-egui/src/lib.rs
• plugins/nih-plug-egui/src/resizable_window.rs
• plugins/nih-plug-egui/src/widgets.rs
• plugins/nih-plug-egui/src/widgets/generic_ui.rs
• plugins/nih-plug-egui/src/widgets/param_slider.rs
• plugins/nih-plug-egui/src/widgets/util.rs
• src/app/clipboard.rs
• src/app/dispatch.rs
• src/app/editing.rs
• src/app/mod.rs
• src/app/navigation.rs
• src/app/persistence.rs
• src/app/scripting.rs
• src/app/sequencer.rs
• src/app/staging.rs
• src/app/undo.rs
• src/bin/desktop/main.rs
• src/block_renderer.rs
• src/commands.rs
• src/engine/audio.rs
• src/engine/dispatcher.rs
• src/engine/link.rs
• src/engine/mod.rs
• src/engine/realtime.rs
• src/engine/sequencer.rs
• src/engine/timing.rs
• src/init.rs
• src/input_egui.rs
• src/input/engine_page.rs
• src/input/help_page.rs
• src/input/main_page.rs
• src/input/mod.rs
• src/input/modal.rs
• src/input/mouse.rs
• src/input/options_page.rs
• src/input/panel.rs
• src/input/patterns_page.rs
• src/lib.rs
• src/main.rs
• src/midi.rs
• src/model/categories.rs
• src/model/demos.rs
• src/model/docs.rs
• src/model/mod.rs
• src/model/onboarding.rs
• src/model/script.rs
• src/page.rs
• src/services/clipboard.rs
• src/services/dict_nav.rs
• src/services/euclidean.rs
• src/services/help_nav.rs
• src/services/mod.rs
• src/services/pattern_editor.rs
• src/services/stack_preview.rs
• src/settings.rs
• src/state/audio.rs
• src/state/color_scheme.rs
• src/state/editor.rs
• src/state/effects.rs
• src/state/file_browser.rs
• src/state/live_keys.rs
• src/state/mod.rs
• src/state/modal.rs
• src/state/mute.rs
• src/state/options.rs
• src/state/panel.rs
• src/state/patterns_nav.rs
• src/state/playback.rs
• src/state/project.rs
• src/state/sample_browser.rs
• src/state/ui.rs
• src/state/undo.rs
• src/theme.rs
• src/views/dict_view.rs
• src/views/engine_view.rs
• src/views/help_view.rs
• src/views/highlight.rs
• src/views/keybindings.rs
• src/views/main_view.rs
• src/views/mod.rs
• src/views/options_view.rs
• src/views/patterns_view.rs
• src/views/render.rs
• src/views/title_view.rs
• src/widgets/mod.rs
• tests/forth.rs
• tests/forth/arithmetic.rs
• tests/forth/case_statement.rs
• tests/forth/chords.rs
• tests/forth/comparison.rs
• tests/forth/context.rs
• tests/forth/control_flow.rs
• tests/forth/definitions.rs
• tests/forth/errors.rs
• tests/forth/euclidean.rs
• tests/forth/generator.rs
• tests/forth/harmony.rs
• tests/forth/harness.rs
• tests/forth/intervals.rs
• tests/forth/list_words.rs
• tests/forth/midi.rs
• tests/forth/notes.rs
• tests/forth/quotations.rs
• tests/forth/ramps.rs
• tests/forth/randomness.rs
• tests/forth/sound.rs
• tests/forth/stack.rs
• tests/forth/temporal.rs
• tests/forth/variables.rs
• xtask/src/main.rs