auto generate ts file?

[greggman]

This is not a real PR. It's just to allow you to take a look. See #89

this uses the tsd-jsdoc npm package
https://www.npmjs.com/package/tsd-jsdoc

it gets a few errors and no idea how close the types
are. Maybe someone more familar with typescript can take a look?

checked in the generated types here

You can run it with

npm install
./node_modules/.bin/grunt jsdoc:ts

[pineapplemachine]

Re #50 (comment): I looked at the examples and didn't actually understand what the purpose of them actually was or how they were meant to run. I'd suggest removing the TypeScript-related examples for the time being if you are having trouble with them, and maybe adding functioning TS-specific examples later on.

[greggman]

I can remove it but I can ship something I can't verify works. As it is now I have zero proof it works

[pineapplemachine]

Zero proof, do you mean the definitions?

If so, that's what npm run testts is for. It runs the TypeScript compiler tsc on a source file at test/src/ts/test.ts using the configuration at test/src/ts/tsconfig.json. If tsc runs without errors, then there cannot be any major issues with the definitions. Any uncaught minor issues are very probably due to documentation errors like the ones you fixed in 43cd3d3

The only way to verify through tests that no more such errors exist is to write TypeScript code utilizing every type and function in twgl. Which is an honorable goal, but a terrible prerequisite for just getting out something that works and can be maintained, since there doesn't seem to be anything like this out there yet.

It is not actually important to run any JavaScript to verify that the definitions are correct. TypeScript does not change language behavior from JavaScript; it only turns certain errors that would normally be runtime errors into compile-time errors - i.e. they happen when you run tsc and not while you're testing it in a browser. If you are encountering errors in the browser when trying to run the output of TypeScript compilation (like if you compiled and tried to run the examples) then there is an error with the implementation - either the example source or the library JS code - not with the definitions.

[pineapplemachine]

Think of TypeScript as a complicated linter. The *.d.ts files are the linter config, and test/src/ts/test.ts is a reference source file which you know follows all the rules you want to enforce.

Your reference file should go through the linter without any errors. If there are any errors, then your linter config isn't right. If there are no errors, then the linter config matches up to what you expected. Executing code that is validated by the linter does not actually say anything about the correctness of the linter config.

Same deal with TypeScript. Executing the output of tsc does not actually say anything about the correctness of the definitions. If npm run testts runs without errors - meaning tsc ran without errors - then that means the *.d.ts definitions succeeded in describing test/src/ts/test.ts as valid TypeScript source.