docs(code): JSDoc pass on exported composables and utils — published export paths lack IDE docs

[IgorShevchik]

Background

Surfaced during the June 2026 multi-angle project audit (engineering review). JSDoc coverage is bimodal: props interfaces are exemplary (consistent @defaultValue, e.g. Select.vue, module.ts options, useComponentProps.ts), but exported functions are thin — and ./composables and ./utils are published exports paths in package.json, so this is consumer-facing IDE experience.

Numbers (audit count: exported functions with a preceding doc block)

• Composables: ≈16/38 (~42%). Zero JSDoc on: defineShortcuts (arguably the most public API of all), useToast, usePortal, useFileUpload, useResizable, useScrollspy, useFilter.
• Utils: ≈11/63 (~17%). runtime/utils/editor.ts 0/16, runtime/utils/form.ts 0/6, runtime/utils/index.ts 1/15.

Fix

A mechanical pass: one-line summary + @param/@returns (and a usage example for the big composables: defineShortcuts, useToast, useOverlay, useFileUpload). No behavior changes; vue-tsc and snapshots stay green.

Related but distinct: missing docs-site pages for 6 composables are tracked separately (docs-site issue); #48 covers the FormField #label slot page.

Priority: P3 — cheap, directly improves IDE experience for every consumer.

[IgorShevchik]

Done in #499. Both published directories are at 100%, and there is now a test that keeps them there.

Your numbers were close but counted only exported functions, which leaves out the interesting half:

	functions	injection keys
src/runtime/composables	11/22	0/14
src/runtime/utils	17/58	0/1

Fifteen injection keys with nothing at all. For formFieldInjectionKey and its siblings that is the difference between a name and a contract — what a Form provides, and what a control underneath it is entitled to read.

The sneakiest gap was invisible from inside the file. Five composables looked documented and weren't:

/**
 * Device Reactivity: Platform and Screen Information
 */
const _useDevice = () => { … }

export const useDevice = /* @__PURE__ */ createSharedComposable(_useDevice)

TypeScript resolves the export, so hovering useDevice() gave you nothing — that block documents _useDevice. Same story for useKbd, useLocale, useConfetti, useContentSearch. Any audit that counts "files containing a doc comment" calls all five documented and moves on.

test/utils/jsdoc-coverage.spec.ts now fails when a new export arrives without a block. Its first version had the same disease as the thing it was policing: it reported 100% while three live exports were invisible to it (export { provideThemeContext }, a destructured createContext pair, a re-export) and it accepted a bare @__NO_SIDE_EFFECTS__ annotation as prose. It knows every export form now, and five mutations each turn it red on its own.

Ten doc blocks also turned out to describe behaviour the code does not have — useResizable claiming percentage sizing where unit defaults to 'px', createSetHandler claiming it never reports active while calling isActive, useFileUpload claiming the drop zone enforces accept when extension entries are filtered out of the list it gets. Writing documentation is a decent bug-finding technique, it turns out.

Worth a look: useOverlay and defineShortcuts now carry worked examples, and every injection key says who provides it and who reads it.

If you are adding an export to either directory, this prompt matches what the guard wants:

Document this export the way the neighbours are documented: what it is for, what the arguments mean where the signature doesn't say it, and for an injection key one line on who provides it and who reads it. Then check every claim against the implementation before you commit — read the return, not the name.

Thanks for the audit — it was a bigger hole than the issue claimed, in the best way. 📚

— from the repo owner

---

Generated by Claude Code