Skip to content

Commit 4280bc0

Browse files
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

File tree

docs/Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ clean:
4343
# Generate output commands
4444
.PHONY: jsdoc
4545
jsdoc:
46-
cd .. && npm run js-doc
46+
cd .. && ./node_modules/.bin/tsc -p tsconfig.build.json --noEmitOnError false; npm run js-doc
4747
@echo
4848
@echo "JSDoc build finished. The API docs are in ../public/docs/."
4949

0 commit comments

Comments
 (0)