Fix Invalid JSDoc Warnings

[ggetz]

As part of the build process, CesiumJS generates TypeScript definitions based off our jsdoc comments.

While we're generally pretty meticulous about having accurate documentation, there are a few instances of invalid jsdoc that have slipped through. The build-ts scripts, which converts our jsdoc to TypeScript definitions, has recently been spitting out a ton of warnings indicating probable issues with our meta tags.

There is a helpful list of common pitfalls the link above, including:

• Use proper @enum notation for enums.
• Use proper @namespace notation for static classes.
• Use proper @function notation for standalone functions.
• Fix Promise markup to actually include the type in all cases, i.e. Promise => Promise<void> or Promise<Cartesian3[]>.

This list likely covers most of the warnings. We should fix theses to ensure we have accurate documentation and accurate TYpeSCript definitions.

[jjhembd]

I captured the warnings in a file to evaluate. There are 1234 warnings, and 1230 of them are "Failed to find parent of doclet...". I think this is a known issue with the tsd-jsdoc plugin.

The plugin repo seems to be dead. I think we might be better off switching to typescript itself to generate the type definitions. Typescript added this functionality shortly after the tsd-jsdoc plugin was developed.

My first quick test of the typescript compiler is throwing a few errors about "requires using private name from module". This may be worth another look when we have time.

[sanjeetsuhag]

While @enum tag is supported by the TypeScript compiler, it doesn't generate a TypeScript enum, instead it generates a namespace in the definition file. Another small issue is the way we export the frozen JS object. For example, see the definitions generated from ArcType.js - (TSPlayground link):

declare const _default: Readonly<{
    /**
     * Straight line that does not conform to the surface of the ellipsoid.
     *
     * @type {Number}
     * @constant
     */
    NONE: number;
    /**
     * Follow geodesic path.
     *
     * @type {Number}
     * @constant
     */
    GEODESIC: number;
    /**
     * Follow rhumb or loxodrome path.
     *
     * @type {Number}
     * @constant
     */
    RHUMB: number;
}>;
export default _default;

If I go from:

export default Object.freeze(ArcType);

to

export default ArcType;

then I lose documentation for the enum values:

export default ArcType;
/**
 * ArcType defines the path that should be taken connecting vertices.
 */
type ArcType = number;
declare namespace ArcType {
    const NONE: number;
    const GEODESIC: number;
    const RHUMB: number;
}

This is with removeComments set to false.

[sanjeetsuhag]

The JSDoc to .d.ts pipeline seems to have several open issues. I left a comment providing an example of the issue we're running into.

[ggetz]

ts-jsdoc is also stopping us from updating our version of jsdoc