voltx / CONTRIBUTING.md

# Contributing to VoltX

## Documentation

### API Doc Parser Spec

- `docsCommand` currently walks every `.ts` file under `src/` and emits markdown for exported functions, interfaces, and type aliases.
    - Extend `parseFile` before adding new declaration shapes so documentation stays complete.
- When enhancing the parser:
    - Normalize all leading whitespace with the `getFullText` helpers
    - Prefer passing structured data (description, tags, examples) into `generateMD`.
    - Avoid baking markdown formatting inside the extractor so the generator can evolve independently.
- Preserve ordering: `parseFile` visits nodes in source order.
    - When adding new collectors, keep this invariant so the docs mirror the file’s story.
- Add unit coverage under `test/dev/docs-parser.test.ts` (or a new spec) whenever you touch comment parsing.
    - Sample TS files with edge-case syntax (generics, overloads, multi-line examples) make regressions easy to catch.
- After updating comments or the parser, build new API docs and inspect the refreshed files in `docs/api/` before submitting changes

### Writing API Documentation (TypeScript)

- Start each source file that ships public APIs with a `@packageDocumentation` tag
    - Give a one-sentence summary on the first line, follow with paragraphs that explain when to reach for the module
    - Avoid other tags in this block so `extractModDocs` can surface clean prose (see `dev/src/commands/docs.ts`).
- Document every exported symbol (functions, interfaces, types, classes, consts) with a JSDoc block placed immediately above the declaration.
    - Keep the first sentence under 121 characters; subsequent sentences can wrap naturally.\
    - Publicly exported symbols are in entry points (`index.ts`, `debug.ts`)
- Structure symbol docs as:
    1. Summary line
    2. Optional paragraphs
    3. `@remarks` for nuance
    4. Any number of `@example` blocks
        - Use markdown code block syntax tagged with `ts` or `typescript`
- The parser doesn't render `@param`, `@returns`, and `@throws` (as of 2025-10-20),
    - Fold critical argument and return-value notes into `@remarks` or provide a short table in markdown
    - When the parser gains tag support, prefer one tag per line (`@param input Signal to watch`) so it can be emitted as a definition list
- Use deliberate naming in overloads and generics; the generator flattens signatures (`extractFnSig`) and shows exactly what the compiler sees.
    - Keep overloads minimal and consider documenting helper types separately if they deserve their own section.

### Writing CSS Documentation

- Place JSDoc-style blocks immediately above the selector or at-rule they describe.
    - The CSS parser associates the next non-empty line that opens a block with the comment so keep unrelated declarations between the comment and selector out of the way.
        - See `extractCSSComments` in `dev/src/commands/css-docs.ts`
- Keep comments under ~180 characters or split them into multiple sentences
    - `generateSemanticsDocs` currently (2025-10-20) discards longer blobs
    - Should answer:
        1. "What does this selector represent?"
        2. "Why does it exist?"
- Explain theme or state-specific overrides (`@media`, `[data-variant]`, etc.) directly in the comment so the semantics page contextualizes duplicated selectors.
    - For shared guidance, prefer separate comments per selector rather than trailing inline notes.
- Name CSS custom properties with the established prefixes (`--color-*`, `--space-*`, `--font-*`, …).
    - The generator buckets them by prefix (`categorizeCSSVar`), so consistent naming keeps the documentation grouped sensibly.
- After editing CSS docs, rebuild and review `docs/css/semantics.md` for accidental duplicates or missing selectors
    - Adjust comments or parser thresholds before committing if the output reads awkwardly