Add more JSDoc types

[kungfooman]

I like to typify code 😅 I don't know how self-explanatory these types are, I happily answer questions.

I confirm I have read the contributing guidelines and signed the Contributor License Agreement.

[willeastcott]

Just a nudge to say that the CI is failing...

[willeastcott]

Can you confirm that npm run docs completes with no errors? I need to add that to the GitHub Actions....

[kungfooman]

Can you confirm that npm run docs completes with no errors? I need to add that to the GitHub Actions....

There are eight errors, two related to this PR (should have used @callback)

Currently rewriting this PR to use @callback style instead of TS inline callback type. Remaining errors:

npm run docs

> playcanvas@1.54.0-dev docs
> jsdoc -c conf-api.json

ERROR: Unable to parse a tag's type expression for source file D:\web\playcanvas-engine-jsdoc\src\framework\app-options.js in line 85 with tag title "type" and text "{typeof Lightmapper}": Invalid type expression "typeof Lightmapper": Expected "|" but "L" found.
ERROR: Unable to parse a tag's type expression for source file D:\web\playcanvas-engine-jsdoc\src\framework\app-options.js in line 90 with tag title "type" and text "{typeof Lightmapper}": Invalid type expression "typeof Lightmapper": Expected "|" but "L" found.
ERROR: Unable to parse a tag's type expression for source file D:\web\playcanvas-engine-jsdoc\src\framework\app-options.js in line 92 with tag title "type" and text "{typeof BatchManager}": Invalid type expression "typeof BatchManager": Expected "|" but "B" found.
ERROR: Unable to parse a tag's type expression for source file D:\web\playcanvas-engine-jsdoc\src\framework\app-options.js in line 97 with tag title "type" and text "{typeof BatchManager}": Invalid type expression "typeof BatchManager": Expected "|" but "B" found.
ERROR: Unable to parse a tag's type expression for source file D:\web\playcanvas-engine-jsdoc\src\framework\app-options.js in line 99 with tag title "type" and text "{typeof XrManager}": Invalid type expression "typeof XrManager": Expected "|" but "X" found.
ERROR: Unable to parse a tag's type expression for source file D:\web\playcanvas-engine-jsdoc\src\framework\app-options.js in line 104 with tag title "type" and text "{typeof XrManager}": Invalid type expression "typeof XrManager": Expected "|" but "X" found.
Can't generate type link. Search output for {{TYPE-ERROR}}
Can't generate type link. Search output for {{TYPE-ERROR}}
npm ERR! code 1
npm ERR! path D:\web\playcanvas-engine-jsdoc
npm ERR! command failed

[willeastcott]

I think you can delete this line right?

[kungfooman]

Yep, thank you!

[kungfooman]

I tried to look into the other errors and it boils down to typeof not being supported:

engine/src/framework/app-options.js

Lines 85 to 104 in e6d3994

	/**
	* The lightmapper.
	*
	* @type {typeof Lightmapper}
	*/
	lightmapper;
	/**
	* The BatchManager.
	*
	* @type {typeof BatchManager}
	*/
	batchManager;
	/**
	* The XrManager.
	*
	* @type {typeof XrManager}
	*/
	xr;

However, I don't know a way to fix it in pure JSDoc. It seems like e.g. @lends {XrManager} is just the right solution, but VSCode/TypeScript don't support that:

microsoft/TypeScript#36771

What VSCode/TypeScript likes most seems to be: @type {{new(app: AppBase): XrManager}}

(basically for the lack of a proper ConstructorOf<XrManager> generic type)

But that trips up JSDoc again... so I feel like @lends is still the most correct way (but TypeScript doesn't supports it yet)

Doc on @lends: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#lends-objectname