CesiumGS/cesium

Ongoing documentation fixes

Open

#11,749 创建于 2024年1月9日

在 GitHub 查看
 (30 评论) (0 反应) (0 负责人)JavaScript (11,758 star) (3,324 fork)batch import
JTCcategory - docgood first issueonramping

描述

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.

贡献者指南