Types: Add "cesiumTypes" JSDoc plugin, update Runtime- and DeveloperError.js

[donmccurdy]

Description

Changes:

• Adds a custom JSDoc plugin, cesiumTypes.js, to help with the gap between syntax supported by JSDoc and syntax needed for type checking. The plugin detects basic JSDoc-incompatible syntax (e.g. 'typeof'), converts that to a special token (currently 'any'), and enforces that this token never leaks into public documentation or .d.ts files. This allows us to use TypeScript syntax for internal code and inline casting, without worrying about breaking tsd-jsdoc. The syntax regex can be expanded as needed.
• Converts RuntimeError.js and DeveloperError.js to ES6 classes, and enables type checking. Only one change was made by hand here, which was adding @ignore (for Types: Separating 'private' vs. 'internal' visibility #13205) and @returns {never} annotations to DeveloperError.throwInstantiationError(). The return type is so the type checker understands that this method always throws; otherwise it will complain that an abstract method does not return the expected type.

Motivated by use cases in #13212, but split out here because that's already a very large PR. :) For example...

  /**
   * @protected
   * @return {typeof BufferPrimitive}
   * @ignore
   */
  _getPrimitiveClass() {
    DeveloperError.throwInstantiationError();
  }

... as a workaround for jsdoc/jsdoc#1349. Returns a BufferPrimitive subclass constructor, not an instance of a class.

In #13212, see:

• packages/engine/Source/Scene/BufferPrimitiveCollection.js
• packages/engine/Source/Core/assert.js

Issue number and link

• Use ES6 "class" as module syntax #8359
• Let us slowly move to Typescript. (instructions inside) #4434

Testing plan

Run:

• npm run tsc
• npm run build-ts
• npm run build-docs

And check documentation, and Cesium.d.ts.

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

PR Dependency Tree

• PR Types: Add "cesiumTypes" JSDoc plugin, update Runtime- and DeveloperError.js #13211 👈

This tree was auto-generated by Charcoal

[github-actions]

Thank you for the pull request, @donmccurdy!

✅ We can confirm we have a CLA on file for you.