Ongoing documentation fixes

[javagl]

There occasionally are "small" fixes for the generated docmentation. These range from "fixing typos" to "fixing broken links" or "fixing type annotations". These usually do not involve rigorous tests, because this only refers to fixes that do not affect the functionality. A corner case is that of TSDoc fixes that may affect the generated typings. These may warrant some scrutiny, but still are not covered by real specs, but maybe only by a few lines in the Specs/TypeScript/index.ts file.

I'd suggest listing these issues here. Everybody can add comments with things that have to be fixed, and we can try to keep track of the things that have been addressed using GitHub [ ] Task checkboxes.

• The Cesium3DTileset.from... functions claim to throw a DeveloperError when the tileset version is not 0.0 or 1.0. (E.g. fromUrl and fromIonAssetId).
  Suggested fix: This should include 1.1 as a valid version number.

• These functions are actually not throwing a DeveloperError, but a RuntimeError, as of this check.
  Suggested fix: Considering that the developer does not have influence on whether ~"the data is valid", it should probably be a RuntimeError (and documented accordingly)

• The ...GeometryUpdater#isDynamic property documentation contains invalid links. (For example, the PolylineGeometryUpdater documentation, generated from PolylineGeometryUpdater, but also other updater classes).
  Suggested fix: It should just omit the part that says

   * If true, all visualization is delegated to the {@link DynamicGeometryUpdater}
   * returned by GeometryUpdater#createDynamicUpdater.
  

  This is an implementation detail that is not relevant for the reader of the documentation.

• The EntityCollection#add function claims to throw a DeveloperError for duplicate IDs, but actually throws a RuntimeError.
  Suggested fix: It should be a DeveloperError. The developer should make sure that there are no duplicate IDs. (In doubt, the developer can trivially check whether an ID is already present)

• The orientation property in the entity constructor options is documented to be of type Property, but it can also be a Quaternion.
  Suggested fix: Change the type to {Property | Quaternion}. Investigate whether the same applies to other properties there.

[javagl]

• There are many places that define a specific type for a certain property (like Cartesian3), but they also define a default value that may be undefined. This is an inconsistency insofar that it's not possible to assign undefined there, and the type of the property should have been Cartesian3 | undefined to begin with. One example (and a regex for finding others) is mentioned in the issue around Can't unset constrainedAxis in typescript without casting  #11475 (comment)
  Suggested fix: Add ... | undefined in all these places

  • Some instances of this have been addressed as part of Updates to typedefs and documentation defaults  #12193

• It's not really a "documentation" fix, but ... way not warrant a full-fledged PR: I think that this updateStages is not used
  Suggested fix: Remove it...

[Tony3141Hui]

• There are many places that define a specific type for a certain property (like Cartesian3), but they also define a default value that may be undefined. This is an inconsistency insofar that it's not possible to assign undefined there, and the type of the property should have been Cartesian3 | undefined to begin with. One example (and a regex for finding others) is mentioned in the issue around Can't unset constrainedAxis in typescript without casting  #11475 (comment)
  Suggested fix: Add ... | undefined in all these places

Analysing ./pakages/**

@default\s+(undefined|null)\s*\n([^/]*\n)*.*@type\s+

No results, means no @type after @default in same annotation block.

@type\s+.*\n([^/]*\n)*.*@default\s+(undefined|null)\s*\n

100+ results, means 100+ targets.

@type\s+.*(undefined|null).*\n([^/]*\n)*.*@default\s+(undefined|null)\s*\n

5 results, means 5 correct, including fixed #11475, in 100+ targets.

[javagl]

(State of 1.121)

• The InterpolationAlgorithm that is linked, for example, from SampledProperty.setInterpolationOptions (but also other places) leads to a 404 right now
  • This was brought up in https://community.cesium.com/t/interpolationalgorithm-page-lost/35086
• The same applies to Packable
• The Packable interface is listed in the "See..." list of Matrix4 and others, and should probably be listed in all implementing classes. But it is not listed in Matrix2 and Matrix3
• I think that positions in this line should be positioned
• The types of the extension... objects here are not {string}, but {object|undefined}

[javagl]

Not really a "documentation" fix, but ...

• Rename https://github.com/CesiumGS/cesium/blob/6c2e520420b95bcb6c8eba0f02c76347cee1dd4b/Apps/Sandcastle/gallery/Globe%20Materials%20%E2%80%93%20Water%20Mask%20Elevation%20Map.html (and the corresponding JPG) to not contain that special "–" character!!! (Ever tried to git add... such a file at a Windows console?)

[javagl]

Also not a "documentation" fix, but maybe part of a cleanup that does not affect functionality:

• I'm pretty sure that frameState.light is not used. If it really is not used, it could be removed.

[javagl]

• The example/snippet that is currently shown at https://cesium.com/learn/ion-sdk/ref-doc/Camera.html works for a new camera. But as soon as this camera is used, it generates a

  "DeveloperError: normalized result is not a number"

  This is related to the position being (0,0,0). I'd go so far and consider this as a bug in the Camera itself, but wanted to keep track of this here.
  Illustration: https://sandcastle.cesium.com/index.html#c=dZFRS8MwFIX/SuhThZE6fbQbQik4UCdzDpRCydLbLZjelCTtmL/eNBWstsvTvfec8yXccIXGklbACTRZEIQTScCIpqI7PwuzgPs+UWiZQNBZcHWXIfc5zirQzOV6AO17JzuDL2mtjLBC4V92wrR1FcPb0MN6byE08B/zyEgRDsxCOBbenlfb/GN2iT+4oKknyVwqvAh+H+RL3RjrPKVqf0FPzB7pyypf79JNvn3YpOk4gMC67c7p9QTMSzdeCmZBbOxZwjJD4s+9qGqlLWm0DCmNLFS1dGsw0b7hn2ApN6Z7YGeNo2E0LkRLRLGY+D/CJTPGKWUj5av4gixYxpHzj6JSsULgYd2Cluzc2Y7z5WM/pJTGkWunk1YpuWf6H/kb
  Edit: When setting globe:false, then it bails out with

  "TypeError: Cannot read properties of undefined (reading 'height')

  Illustration: https://sandcastle.cesium.com/index.html#c=dZFRS8MwFIX/SuhThZE6fdNuCKPgQJ3MOZgURpbedsH0piRpxxT/u2kqOG2Xp9x7zvluuOEKjSWNgANoMiEIBzIDI+qSrn0vTAPu65lCywSCToMR+UyRkEKqHdyQnEkDKX5d3KbIPY2zEjRztA5Lu9rJzuCvtFJGWKHw78QZ09bdGF6HHtZ5M6GB/5h7RopQMAthX3h9mq+2b6Nz/JMBdTVI5lLhWfDmJJ/r2ljnyVXzC3pkdk+f59vFOlluV/fLJOkHEFi78zG9HIB56cpLwSiIjT1KmLZrb8+dKCulLam1DCmNLJSVdGsw0a7m72ApN6Z9YGuNo9NonImGiGwy8KuES2aMU/JayhfxAWkwjSPn70WlYpnAYtGAluzY2vbj6UPXpJTGkSuHk1YpuWP6H/kb
  (I'll probably open a broader issue for all this soon...)

[javagl]

• Not sure what the "callback" and "log messages" part refers to at

  cesium/packages/engine/Source/Scene/GltfPipeline/getComponentReader.js

  Line 135 in 3055909

  * A callback function that logs messages.

[javagl]

• Not really a "documentation fix", but ... that , Property.equals part should be replaced by a Property.equals call, at

  • cesium/packages/engine/Source/DataSources/CompositeMaterialProperty.js

    Line 118 in 1c892c8

    this._composite.equals(other._composite, Property.equals))

  • cesium/packages/engine/Source/DataSources/CompositePositionProperty.js

    Line 144 in 1c892c8

    this._composite.equals(other._composite, Property.equals))

  • cesium/packages/engine/Source/DataSources/CompositeProperty.js

    Line 138 in 1c892c8

    this._intervals.equals(other._intervals, Property.equals))

  • cesium/packages/engine/Source/DataSources/TimeIntervalCollectionPositionProperty.js

    Line 144 in 1c892c8

    this._intervals.equals(other._intervals, Property.equals) && //

  • cesium/packages/engine/Source/DataSources/TimeIntervalCollectionProperty.js

    Line 126 in 1c892c8

    this._intervals.equals(other._intervals, Property.equals))

[javagl]

• The Axis class and the associated ..._UP_TO_..._UP matrices do not appear in the documentation.

[javagl]

• The one that was brought up in an obvious error in the documentation comments in OrthographicFrustum.js. #12537 seems uncontroversial for me...

[javagl]

Not actually a documentation fix, but rather a bug fix:

• TileCoordinatesImageryProvider.minimumLevel claims to return a {number}, but returns undefined...

[javagl]

• I'm pretty sure that the word "less" in "Enabling this option will allow for less frustums in the multi-frustum" should be "fewer" ...