AnimStateGraph: Add JSDoc types

[kungfooman]

Currently there are no types in playcanvas.d.ts:

This PR implements all the types the class AnimStateGraph accepts:

This enables Intellisense for e.g. PC Viewer:

Fixing ESLint is not so easy, because I am running into some VSCode/TypeScript issue or so: eslint/eslint#14235

I confirm I have signed the Contributor License Agreement.

[yaustar]

@willeastcott @ellthompson is this a PR that we can review + merge?

[Maksims]

How does this affects docs generation?
Also, this is something we haven't done before, and looks like specifically for TypeScript, not for everyone else.

[kungfooman]

How does this affects docs generation?

Good point, it currently produces a 404, which should be fixed to produce a proper object description (maybe inline):

Also, this is something we haven't done before, and looks like specifically for TypeScript, not for everyone else.

I mainly did this for playcanvas-viewer, which is written in TypeScript, to get rid of // @ts-ignore cases. It also helps JavaScript developers in Visual Studio Code or any other editor that supports JavaScript IntelliSense.

[vmwxiong]

How does this affects docs generation?
Also, this is something we haven't done before, and looks like specifically for TypeScript, not for everyone else.

Eavesdropping in, but I'd love to see support for explicit TS definition contributions somehow. Been doing a bunch of work to get proper types for some things, but not sure how I could possibly contribute the work to the project at all: https://gist.github.com/vmwxiong/eabc60834b32801f5a38de99f4acad80

[kungfooman]

Eavesdropping in, but I'd love to see support for explicit TS definition contributions somehow.

The generated playcanvas.d.ts is kinda as "proper" as it gets, only that generating it through JSDoc feels a bit convoluted. The custom doc generation from it doesn't make it more straight forward either, like fixing something in this repo needs another fix in https://github.com/playcanvas/playcanvas-jsdoc-template e.g.

For more "advanced" typing like yours it would make sense to append it directly to playcanvas.d.ts after its generation, so it's shared for anyone who installed PlayCanvas through npm. Putting extra typing clues in too many places could make it overly confusing though, so one should try to make use of JSDoc whenever possible (and keep playcanvas-jsdoc-template synched to display types in an informative/easy/understandable way)

[hixio-mh]

Reviews and change

[kungfooman]

Any is good enough, we shouldn't overcomplicate types like this.

[vmwxiong]

any is extremely painful to with with as it blows up attempts at building type-safe code, and you need to write and use convoluted type guards every time you want to use something typed with an any value.

Disappointed to see the project not moving to support type safe definitions.

[willeastcott]

@vmwxiong I think you missed this conversation: playcanvas/model-viewer#98 (comment)

The plan is to make AnimStateGraph internal. So this is no longer an issue.

You may have also noticed this week that I have submitted several issues on the repo about improving the Typescript definitions. So saying that 'the project is not moving to support type safe definitions' is not fair or accurate, IMHO. The only time it is difficult to solve typing definitions problems is when it negatively impacts the quality of the API reference manual. Otherwise, everybody is excited to be improving the quality of the typings.

[vmwxiong]

Ah, thanks for the clarification, apologies for jumping to conclusions

…

On Thu, Nov 11, 2021, 10:52 AM Will Eastcott ***@***.***> wrote: @vmwxiong <https://github.com/vmwxiong> I think you missed this conversation: playcanvas/model-viewer#98 (comment) <playcanvas/model-viewer#98 (comment)> The plan is to make AnimStateGraph internal. So this is no longer an issue. You may have also noticed this week that I have submitted several issues on the repo about improving the Typescript definitions. So saying that 'the project is not moving to support type safe definitions' is not fair or accurate, IMHO. The only time it is difficult to solve typing definitions problems is when it negatively impacts the quality of the API reference manual. Otherwise, everybody is excited to be improving the quality of the typings. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2986 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ARC2QNQR5Y6NZ2FVFC5J5NLULQGIPANCNFSM4ZORQZJA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.