search

greggman / twgl.js

A Tiny WebGL helper Library
http://twgljs.org
MIT License
2.67k stars 260 forks source link

auto generate ts file? #97

Closed greggman closed 5 years ago

greggman commented 5 years ago

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 commented 5 years ago

Re https://github.com/greggman/twgl.js/issues/50#issuecomment-454098843: 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 commented 5 years ago

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 commented 5 years ago

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 https://github.com/greggman/twgl.js/pull/97/commits/43cd3d3dbd23eb64609da064381dfab3d59c447c

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 commented 5 years ago

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.