search

ceifa / wasmoon

A real lua 5.4 VM with JS bindings made with webassembly
MIT License
449 stars 29 forks source link

Adds some documentation to public facing classes and functions #106

Open PlaryWasTaken opened 5 months ago

PlaryWasTaken commented 5 months ago

Pretty much described in the title, adds some documentation, mainly for public facing functions and classes, i would have typed the options of factory.ts - createEngine function, but i don't understand the project enough. I did use AI to help me write some of these types

ceifa commented 5 months ago

There is some lint errors, can you fix them?

ceifa commented 5 months ago

Also I think it's a little bit weird to use TS with JSDoc, is it common in libraries?

PlaryWasTaken commented 5 months ago

It provides better description on what a function does image Example above in a Jetbrains IDE, Typescript does add a type system but you don't have any actual documentation when you only use TS, only type info. Fixed linting with npm run lint, tested with npm run lint:no-fix no errors returned

PlaryWasTaken commented 5 months ago

Having these descriptions helps to aid in ambiguity where you might have a certain idea of how something works but you're not sure, thats why i also wanted to type the options in createEngine, but im not sure what every one of those options does under the hood

PlaryWasTaken commented 5 months ago

Oh, i forgot that tsconfig has "removeComents" as true, for JSDoc to be able to be used for this "removeComments¨ has to be false, is there any reason for this to be set to true?

ceifa commented 5 months ago

Oh, i forgot that tsconfig has "removeComents" as true, for JSDoc to be able to be used for this "removeComments¨ has to be false, is there any reason for this to be set to true?

Some libraries have comments on their code, this option removes it to decrease the bundle size.

PlaryWasTaken commented 5 months ago

Also I think it's a little bit weird to use TS with JSDoc, is it common in libraries?

Well, mongoose uses them, and i've seen some other libs use them too

ceifa commented 5 months ago

Well, mongoose uses them, and i've seen some other libs use them too

Mongoose uses JS + JSDoc...

Just found out there is a TSDoc: https://tsdoc.org/

PlaryWasTaken commented 5 months ago

Well, mongoose uses them, and i've seen some other libs use them too

Mongoose uses JS + JSDoc...

Just found out there is a TSDoc: https://tsdoc.org/

Well, i tried to use mongoose as an example since it was the first one that came to mind, and it was a bad example, so im sorry. Typescript does support JSDoc, and TSDoc is the same as JSDoc but a reduced subset https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html I will convert my JSDoc comments to the reduced subset that typescript accepts

ceifa commented 4 months ago

I would like these comments to be only on the .d.ts files, to not affect the bundle size: https://github.com/microsoft/TypeScript/issues/14619

But since this is not something on TS yet, I just have to check how this affects our bundle and it's good to merge.

PlaryWasTaken commented 3 months ago

Ill get to it soon, thanks for helping with the comments for CreateEngineOptions Also there is a workaround to only adding comments in declaration files in the issue you mentioned, tough it requires a change in the build scripts and i havent tested it yet

          A sane workaround:
tsc --removeComments && tsc --declaration --emitDeclarationOnly

With tsconfig.json options:

"removeComments": false,
"declaration": false,

Builds stripped JS, then emits declarations with JSDoc preserved.

Originally posted by @michal-kapala in https://github.com/microsoft/TypeScript/issues/14619#issuecomment-1971477006

RodrigoDornelles commented 6 days ago

@ceifa would like to have access to more docs, can I continue new PR just by making the remaining adjustments?

indded, what do you think about me preparing a workflow with github-pages and some documentation generator tool? jsdoc, doxygen, something like that...?