Proposal: Use type declarations over @typedef

Problem

The engine uses JSDoc @typedef {object} Type notation to declare types. This works for using them and will show in typedoc but they are not exported in playcanvas.d.ts unlike if we used export type Type ... like in typescript

Proposal

JS supports import external types files e.g. If you have a file called types.d.ts with a type like this:

export type Type {
   name: string;
}

you can import it into JS using the @import keyword just like you can with @typedefs from JS files

/** @import { Type } from './type' */

The idea would be to have a types.d.ts file in subfolders - similar to the way we have constants.js to keep the type files organised and scopes to particular areas.

Pros

• Can explicitly exported in the NPM package (and can control visibility in API reference since typedoc respects export keyword)
• Typescript types declarations will behave the same way for development (including examples since type files will be ignored since examples uses the bundled playcanvas.d.ts)
• Typescript types are bundled in with no additional configuration
• Type fixing StandardMaterial and ScriptType can be removed as extra method types can be declared directly and bundled in without any custom plugins
• Callback declarations can be converted into type declarations
• Constants for enums can now be converted directly into types reducing code size

Cons

• Mixture of .d.ts and .js files in the codebase
• Will take some time to convert @typedefs to type declarations (can be mostly automated however)