Commit 4280bc0
authored
docs: compile TypeScript before running JSDoc (#482)
## Problem
Fixes #477.
TypeScript source files (`uuid.ts`, `local-time.ts`, `tuple.ts`,
`big-decimal.ts`, `version-number.ts`, `execution-profile.ts`, etc.)
were silently excluded from the generated API documentation.
JSDoc cannot parse TypeScript syntax — it errors out immediately on type
annotations, private class fields, and `import =` statements. As a
result, the `jsdoc ./lib -r` invocation scanned `lib/` recursively but
skipped every `.ts` file.
## Fix
Run `tsc` before `jsdoc` in the `jsdoc` Makefile target:
```makefile
cd .. && ./node_modules/.bin/tsc -p tsconfig.build.json --noEmitOnError false; npm run js-doc
```
`tsc` compiles `.ts` files in-place to `.js` alongside the sources
(these are gitignored, per `lib/types/.gitignore`). JSDoc then picks
them up normally via its default `.js` pattern. JSDoc comments are
preserved in the compiled output because `noEmitOnError` is not set in
`tsconfig.build.json`.
`--noEmitOnError false` is needed because `tsc` reports type errors in a
clean checkout or in the docs CI environment — `index.d.ts` and
`index.js` are generated artifacts of the Napi/Rust build step (`napi
build`) which does not run there. With `--noEmitOnError false`, `tsc`
still emits the `.js` files and exits with code 0, so `make` always
continues to the JSDoc step.
## Known limitation
Parameter type information (the Type column in JSDoc parameter tables)
is not populated for parameters typed only via TypeScript annotations.
JSDoc can only read types from explicit `@param {Type}` tags in the
comment, not from TypeScript type syntax stripped during compilation.
This is a known limitation of the compile-first approach and is out of
scope for this fix.1 parent 75378b2 commit 4280bc0
1 file changed
Lines changed: 1 addition & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
43 | 43 | | |
44 | 44 | | |
45 | 45 | | |
46 | | - | |
| 46 | + | |
47 | 47 | | |
48 | 48 | | |
49 | 49 | | |
| |||
0 commit comments