Refactor JSDocs for events

[willeastcott]

Refactor the JSDoc blocks for all events in the engine:

• Event blocks now appear first in the class definition.
• Events like add and add:[name] have been combined under add (as variants).
• Each event has a static string property (this is required or tsc does not see the events). The static string is just a mechanism to document the event - the developer is not expected to use it in their code (although there's no harm in doing that).
• Every event now has an @example tag written in modern JS.

This PR enables all events to now show in the new TypeDoc API reference manual. As an example, here's the new look of the SpriteComponent API ref page:

And:

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

[Maksims]

With replacing event string with constants, is there info on how V8 actually handles constant strings in the code?
It might be that todays V8 situation that there is very little difference in performance when using constant that points to a string vs actual string.

[willeastcott]

@Maksims I don't have any information on that, but:

• These are static (class) properties. They have negligible overhead.
• The static strings are just a mechanism to document the events - the developer is not expected to use the EVENT_ names in their code (although there's no harm in doing that). Instead, they'll continue to use the string literals.

[kungfooman]

This PR enables all events to now show in the new TypeDoc API reference manual.

Will they still show in normal JSDoc (npm run docs)?

Somehow strange that we have to increase build size for docs.

[Maksims]

@Maksims I don't have any information on that, but:

• These are static (class) properties. They have negligible overhead.
• The static strings are just a mechanism to document the events - the developer is not expected to use the EVENT_ names in their code (although there's no harm in doing that). Instead, they'll continue to use the string literals.

Is there a way to make new docs respect @event or some alternative. As the name of an event in docs is also best to be same as actual event name.

This is convenient:

[kungfooman]

Is there a way to make new docs respect @event or some alternative.

We aren't the first asking for this feature: https://github.com/TypeStrong/typedoc/issues?q=jsdoc+event

Unfortunately the maintainer doesn't care about @event and just closes every issue without proper solution, so we pretty much have two options:

1. Give in to strange ways of doing things for lack of native event support in typedoc
2. Develop a typedoc plugin

[willeastcott]

Somehow strange that we have to increase build size for docs.

TypeDoc/tsc may be strange in some limited circumstances, but if it's an overall win, I can live with a teeny tiny size increase.

[mvaligursky]

so glad you preserved the types of arguments too.

[mvaligursky]

What an effort!

@kpal81xd - any events you might need to update similarly for the Gizmos?