Feat: WIP terse code documentation

crates/ratatui/src/category_list.rs

@@ -1,3 +1,5 @@
+//! Collapsible categorized list widget with section headers.
+
 use ratatui::layout::Rect;
 use ratatui::style::{Color, Modifier, Style};
 use ratatui::widgets::{Block, Borders, List, ListItem};
@@ -5,17 +7,20 @@ use ratatui::Frame;
 
 use crate::theme;
 
+/// Entry in a category list: either a section header or a leaf item.
 pub struct CategoryItem<'a> {
     pub label: &'a str,
     pub is_section: bool,
     pub collapsed: bool,
 }
 
+/// What is currently selected: a leaf item or a section header.
 pub enum Selection {
     Item(usize),
     Section(usize),
 }
 
+/// Scrollable list with collapsible section headers.
 pub struct CategoryList<'a> {
     items: &'a [CategoryItem<'a>],
     selection: Selection,

crates/ratatui/src/confirm.rs

@@ -1,3 +1,5 @@
+//! Yes/No confirmation dialog widget.
+
 use crate::theme;
 use ratatui::layout::{Alignment, Constraint, Layout, Rect};
 use ratatui::style::Style;
@@ -7,6 +9,7 @@ use ratatui::Frame;
 
 use super::ModalFrame;
 
+/// Modal dialog with Yes/No buttons.
 pub struct ConfirmModal<'a> {
     title: &'a str,
     message: &'a str,

crates/ratatui/src/editor.rs

@@ -1,3 +1,5 @@
+//! Script editor widget with completion, search, and sample finder popups.
+
 use std::cell::Cell;
 
 use crate::theme;
@@ -10,8 +12,10 @@ use ratatui::{
 };
 use tui_textarea::TextArea;
 
+/// Callback that syntax-highlights a single line, returning styled spans (bool = annotation).
 pub type Highlighter<'a> = &'a dyn Fn(usize, &str) -> Vec<(Style, String, bool)>;
 
+/// Metadata for a single autocomplete entry.
 #[derive(Clone)]
 pub struct CompletionCandidate {
     pub name: String,
@@ -78,6 +82,7 @@ impl SearchState {
     }
 }
 
+/// Multi-line text editor backed by tui_textarea.
 pub struct Editor {
     text: TextArea<'static>,
     completion: CompletionState,
@@ -702,6 +707,7 @@ impl Editor {
     }
 }
 
+/// Score a fuzzy match of `query` against `target`. Lower is better; `None` if no match.
 pub fn fuzzy_match(query: &str, target: &str) -> Option<usize> {
     let target_lower: Vec<char> = target.to_lowercase().chars().collect();
     let query_lower: Vec<char> = query.to_lowercase().chars().collect();

crates/ratatui/src/file_browser.rs

@@ -1,3 +1,5 @@
+//! File/directory browser modal widget.
+
 use crate::theme;
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Color, Style};
@@ -7,6 +9,7 @@ use ratatui::Frame;
 
 use super::ModalFrame;
 
+/// Modal listing files and directories with a filter input line.
 pub struct FileBrowserModal<'a> {
     title: &'a str,
     input: &'a str,

crates/ratatui/src/hint_bar.rs

@@ -1,8 +1,11 @@
+//! Bottom-bar keyboard hint renderer.
+
 use ratatui::text::{Line, Span};
 use ratatui::style::Style;
 
 use crate::theme;
 
+/// Build a styled line of key/action pairs for the hint bar.
 pub fn hint_line(pairs: &[(&str, &str)]) -> Line<'static> {
     let theme = theme::get();
     let key_style = Style::default().fg(theme.hint.key);

crates/ratatui/src/lissajous.rs

@@ -1,3 +1,5 @@
+//! Lissajous XY oscilloscope widget using braille characters.
+
 use crate::theme;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
@@ -9,6 +11,7 @@ thread_local! {
     static PATTERNS: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
 }
 
+/// XY oscilloscope plotting left vs right channels as a Lissajous curve.
 pub struct Lissajous<'a> {
     left: &'a [f32],
     right: &'a [f32],

crates/ratatui/src/list_select.rs

@@ -1,3 +1,5 @@
+//! Scrollable single-select list widget with cursor highlight.
+
 use crate::theme;
 use ratatui::layout::Rect;
 use ratatui::style::{Modifier, Style};
@@ -5,6 +7,7 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::Paragraph;
 use ratatui::Frame;
 
+/// Scrollable list with a highlighted cursor and selected-item marker.
 pub struct ListSelect<'a> {
     items: &'a [String],
     selected: usize,

crates/ratatui/src/modal.rs

@@ -1,9 +1,12 @@
+//! Centered modal frame with border and title.
+
 use crate::theme;
 use ratatui::layout::Rect;
 use ratatui::style::{Color, Style};
 use ratatui::widgets::{Block, Borders, Clear, Paragraph};
 use ratatui::Frame;
 
+/// Centered modal overlay with titled border.
 pub struct ModalFrame<'a> {
     title: &'a str,
     width: u16,

crates/ratatui/src/nav_minimap.rs

@@ -1,3 +1,5 @@
+//! Page navigation minimap showing a 3x2 grid of tiles.
+
 use crate::theme;
 use ratatui::layout::{Alignment, Rect};
 use ratatui::style::Style;

crates/ratatui/src/props_form.rs

@@ -1,3 +1,5 @@
+//! Vertical label/value property form renderer.
+
 use ratatui::layout::Rect;
 use ratatui::style::{Modifier, Style};
 use ratatui::widgets::Paragraph;
@@ -5,6 +7,7 @@ use ratatui::Frame;
 
 use crate::theme;
 
+/// Render a vertical list of label/value pairs with selection highlight.
 pub fn render_props_form(frame: &mut Frame, area: Rect, fields: &[(&str, &str, bool)]) {
     let theme = theme::get();
 

crates/ratatui/src/sample_browser.rs

@@ -1,3 +1,5 @@
+//! Tree-view sample browser with search filtering.
+
 use crate::theme;
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Modifier, Style};
@@ -5,6 +7,7 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Borders, Paragraph};
 use ratatui::Frame;
 
+/// Node type in the sample tree.
 #[derive(Clone, Copy)]
 pub enum TreeLineKind {
     Root { expanded: bool },
@@ -12,6 +15,7 @@ pub enum TreeLineKind {
     File,
 }
 
+/// A single row in the sample browser tree.
 #[derive(Clone)]
 pub struct TreeLine {
     pub depth: u8,
@@ -21,6 +25,7 @@ pub struct TreeLine {
     pub index: usize,
 }
 
+/// Tree-view browser for navigating sample folders.
 pub struct SampleBrowser<'a> {
     entries: &'a [TreeLine],
     cursor: usize,

crates/ratatui/src/scope.rs

@@ -1,3 +1,5 @@
+//! Oscilloscope waveform widget using braille characters.
+
 use crate::theme;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
@@ -9,12 +11,14 @@ thread_local! {
     static PATTERNS: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
 }
 
+/// Rendering direction for the oscilloscope.
 #[derive(Clone, Copy)]
 pub enum Orientation {
     Horizontal,
     Vertical,
 }
 
+/// Single-channel oscilloscope using braille dot plotting.
 pub struct Scope<'a> {
     data: &'a [f32],
     orientation: Orientation,

crates/ratatui/src/scroll_indicators.rs

@@ -1,13 +1,17 @@
+//! Up/down arrow scroll indicators for bounded lists.
+
 use ratatui::layout::Rect;
 use ratatui::style::{Color, Style};
 use ratatui::widgets::Paragraph;
 use ratatui::Frame;
 
+/// Horizontal alignment for scroll indicators.
 pub enum IndicatorAlign {
     Center,
     Right,
 }
 
+/// Render up/down scroll arrows when content overflows.
 pub fn render_scroll_indicators(
     frame: &mut Frame,
     area: Rect,

crates/ratatui/src/search_bar.rs

@@ -1,3 +1,5 @@
+//! Inline search bar with active/inactive styling.
+
 use ratatui::layout::Rect;
 use ratatui::style::Style;
 use ratatui::text::{Line, Span};
@@ -6,6 +8,7 @@ use ratatui::Frame;
 
 use crate::theme;
 
+/// Render a `/query` search bar.
 pub fn render_search_bar(frame: &mut Frame, area: Rect, query: &str, active: bool) {
     let theme = theme::get();
     let style = if active {

crates/ratatui/src/section_header.rs

@@ -1,3 +1,5 @@
+//! Section header with horizontal divider for engine-view panels.
+
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Modifier, Style};
 use ratatui::widgets::Paragraph;
@@ -5,6 +7,7 @@ use ratatui::Frame;
 
 use crate::theme;
 
+/// Render a section title with a horizontal divider below it.
 pub fn render_section_header(frame: &mut Frame, title: &str, focused: bool, area: Rect) {
     let theme = theme::get();
     let [header_area, divider_area] =

crates/ratatui/src/sparkles.rs

@@ -1,3 +1,5 @@
+//! Decorative particle effect using random Unicode glyphs.
+
 use crate::theme;
 use rand::Rng;
 use ratatui::buffer::Buffer;
@@ -14,6 +16,7 @@ struct Sparkle {
     life: u8,
 }
 
+/// Animated sparkle particles for visual flair.
 #[derive(Default)]
 pub struct Sparkles {
     sparkles: Vec<Sparkle>,

crates/ratatui/src/spectrum.rs

@@ -1,3 +1,5 @@
+//! 32-band frequency spectrum bar display.
+
 use crate::theme;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
@@ -6,6 +8,7 @@ use ratatui::widgets::Widget;
 
 const BLOCKS: [char; 8] = ['\u{2581}', '\u{2582}', '\u{2583}', '\u{2584}', '\u{2585}', '\u{2586}', '\u{2587}', '\u{2588}'];
 
+/// 32-band spectrum analyzer using block characters.
 pub struct Spectrum<'a> {
     data: &'a [f32; 32],
     gain: f32,

crates/ratatui/src/text_input.rs

@@ -1,3 +1,5 @@
+//! Single-line text input modal with optional hint.
+
 use crate::theme;
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Color, Style};
@@ -7,6 +9,7 @@ use ratatui::Frame;
 
 use super::ModalFrame;
 
+/// Modal dialog with a single-line text input.
 pub struct TextInputModal<'a> {
     title: &'a str,
     input: &'a str,

crates/ratatui/src/vu_meter.rs

@@ -1,3 +1,5 @@
+//! Stereo VU meter with dB-scaled level display.
+
 use crate::theme;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
@@ -8,6 +10,7 @@ const DB_MIN: f32 = -48.0;
 const DB_MAX: f32 = 3.0;
 const DB_RANGE: f32 = DB_MAX - DB_MIN;
 
+/// Stereo VU meter displaying left/right levels in dB.
 pub struct VuMeter {
     left: f32,
     right: f32,

crates/ratatui/src/waveform.rs

@@ -1,3 +1,5 @@
+//! Filled waveform display using braille characters.
+
 use crate::scope::Orientation;
 use crate::theme;
 use ratatui::buffer::Buffer;
@@ -10,6 +12,7 @@ thread_local! {
     static PATTERNS: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
 }
 
+/// Filled waveform renderer using braille dot plotting.
 pub struct Waveform<'a> {
     data: &'a [f32],
     orientation: Orientation,