a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
hypermedia
frontend
signals
docs: contributing guidelines
* added features to docsite home
* global state docs
+75
-14
+54
CONTRIBUTING.md
+54
CONTRIBUTING.md
···
1
+
# Contributing to VoltX
2
+
3
+
## Documentation
4
+
5
+
### API Doc Parser Spec
6
+
7
+
- `docsCommand` currently walks every `.ts` file under `src/` and emits markdown for exported functions, interfaces, and type aliases.
8
+
- Extend `parseFile` before adding new declaration shapes so documentation stays complete.
9
+
- When enhancing the parser:
10
+
- Normalize all leading whitespace with the `getFullText` helpers
11
+
- Prefer passing structured data (description, tags, examples) into `generateMD`.
12
+
- Avoid baking markdown formatting inside the extractor so the generator can evolve independently.
13
+
- Preserve ordering: `parseFile` visits nodes in source order.
14
+
- When adding new collectors, keep this invariant so the docs mirror the file’s story.
15
+
- Add unit coverage under `test/dev/docs-parser.test.ts` (or a new spec) whenever you touch comment parsing.
16
+
- Sample TS files with edge-case syntax (generics, overloads, multi-line examples) make regressions easy to catch.
17
+
- After updating comments or the parser, build new API docs and inspect the refreshed files in `docs/api/` before submitting changes
18
+
19
+
### Writing API Documentation (TypeScript)
20
+
21
+
- Start each source file that ships public APIs with a `@packageDocumentation` tag
22
+
- Give a one-sentence summary on the first line, follow with paragraphs that explain when to reach for the module
23
+
- Avoid other tags in this block so `extractModDocs` can surface clean prose (see `dev/src/commands/docs.ts`).
24
+
- Document every exported symbol (functions, interfaces, types, classes, consts) with a JSDoc block placed immediately above the declaration.
25
+
- Keep the first sentence under 121 characters; subsequent sentences can wrap naturally.\
26
+
- Publicly exported symbols are in entry points (`index.ts`, `debug.ts`)
27
+
- Structure symbol docs as:
28
+
1. Summary line
29
+
2. Optional paragraphs
30
+
3. `@remarks` for nuance
31
+
4. Any number of `@example` blocks
32
+
- Use markdown code block syntax tagged with `ts` or `typescript`
33
+
- The parser doesn't render `@param`, `@returns`, and `@throws` (as of 2025-10-20),
34
+
- Fold critical argument and return-value notes into `@remarks` or provide a short table in markdown
35
+
- 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
36
+
- Use deliberate naming in overloads and generics; the generator flattens signatures (`extractFnSig`) and shows exactly what the compiler sees.
37
+
- Keep overloads minimal and consider documenting helper types separately if they deserve their own section.
38
+
39
+
### Writing CSS Documentation
40
+
41
+
- Place JSDoc-style blocks immediately above the selector or at-rule they describe.
42
+
- 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.
43
+
- See `extractCSSComments` in `dev/src/commands/css-docs.ts`
44
+
- Keep comments under ~180 characters or split them into multiple sentences
45
+
- `generateSemanticsDocs` currently (2025-10-20) discards longer blobs
46
+
- Should answer:
47
+
1. "What does this selector represent?"
48
+
2. "Why does it exist?"
49
+
- Explain theme or state-specific overrides (`@media`, `[data-variant]`, etc.) directly in the comment so the semantics page contextualizes duplicated selectors.
50
+
- For shared guidance, prefer separate comments per selector rather than trailing inline notes.
51
+
- Name CSS custom properties with the established prefixes (`--color-*`, `--space-*`, `--font-*`, …).
52
+
- The generator buckets them by prefix (`categorizeCSSVar`), so consistent naming keeps the documentation grouped sensibly.
53
+
- After editing CSS docs, rebuild and review `docs/css/semantics.md` for accidental duplicates or missing selectors
54
+
- Adjust comments or parser thresholds before committing if the output reads awkwardly
+12
-2
docs/.vitepress/config.ts
+12
-2
docs/.vitepress/config.ts
···
30
30
items: [{ text: "Volt CSS", link: "/css/volt-css" }, { text: "Reference", link: "/css/semantics" }],
31
31
},
32
32
{ text: "Specs", collapsed: true, items: u.scanDir("spec", "/spec") },
33
-
{ text: "API Reference", collapsed: true, items: u.scanDir("api", "/api") },
34
-
{ text: "Internals", collapsed: false, items: u.scanDir("internals", "/internals") },
33
+
{
34
+
text: "API Reference",
35
+
collapsed: true,
36
+
items: u.scanDir("api", "/api"),
37
+
docFooterText: "Auto-generated API Docs",
38
+
},
39
+
{
40
+
text: "Internals",
41
+
collapsed: false,
42
+
items: u.scanDir("internals", "/internals"),
43
+
docFooterText: "Auto-generated CSS Docs",
44
+
},
35
45
],
36
46
socialLinks: [{ icon: "github", link: "https://github.com/stormlightlabs/volt" }],
37
47
},
+3
-5
docs/global-state.md
+3
-5
docs/global-state.md
···
1
1
# Global State
2
2
3
-
VoltX provides built-in global state management through special variables and the global store. These features enable sharing state across components, accessing metadata, and coordinating behavior without external dependencies.
3
+
VoltX provides built-in global state management through special variables and a globally available store.
4
+
These features enable sharing state across components, accessing metadata, and coordinating behavior without external dependencies.
4
5
5
6
## Overview
6
7
···
210
211
<div data-volt
211
212
data-volt-state='{"initialized": false}'
212
213
data-volt-init="initialized.set(true)">
213
-
214
214
<p data-volt-text="initialized"></p>
215
215
<!-- Displays: true -->
216
216
</div>
···
222
222
<div data-volt
223
223
data-volt-state='{"count": 0, "log": []}'
224
224
data-volt-init="$probe('count', v => log.push(v))">
225
-
226
225
<button data-volt-on-click="count.set(count.get() + 1)">Increment</button>
227
226
<p data-volt-text="log.join(', ')"></p>
228
227
<!-- Displays: "0, 1, 2, ..." -->
···
236
235
id="main"
237
236
data-volt-state='{"rootId": ""}'
238
237
data-volt-init="rootId.set($origin.id)">
239
-
240
238
<p data-volt-text="rootId"></p>
241
239
<!-- Displays: "main" -->
242
240
</div>
···
419
417
<!-- Add todo form -->
420
418
<div data-volt data-volt-state='{"newTodo": ""}'>
421
419
<input data-volt-model="newTodo" data-volt-pin="todoInput" />
422
-
<button data-volt-on-click="$store.get('todos').push({ text: newTodo.get(), done: false }); newTodo.set(''); $pins.todoInput.focus()">
420
+
<button data-volt-on-click="$store.set('todos', [...$store.get('todos'), { text: newTodo.get(), done: false }]); newTodo.set(''); $pins.todoInput.focus()">
423
421
Add
424
422
</button>
425
423
</div>
+6
-7
docs/index.md
+6
-7
docs/index.md
···
18
18
link: /api-examples
19
19
20
20
features:
21
-
- title: Feature A
22
-
details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
23
-
- title: Feature B
24
-
details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
25
-
- title: Feature C
26
-
details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
21
+
- title: Reactive
22
+
details: Signal-driven rendering keeps your markup in sync with data.
23
+
- title: Hypermedia Powered
24
+
details: Built-in hypermedia helpers stream link and form updates across HTTP and WebSocket transports.
25
+
- title: Expandable
26
+
details: A modular plugin system lets you ship custom bindings, transports, and diagnostics
27
27
---
28
-