CesiumGS / CesiumGS/cesium

Types: Separating 'private' vs. 'internal' visibility

Open
#13,205 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
15.7k
Forks
3.9k
Avg merge
4d 6h
Merged PRs (30d)
34

Description

As we start to enable type checking on more files with `// @ts-check`, one recurring issue is that many properties and methods — intended for internal use or access from unit tests — are annotated with the JSDoc [`@private`](https://jsdoc.app/tags-private) tag. While we do want these members to be hidden from the published documentation, we don't want to use `// @ts-expect-error` in all of the intentional internal places that we actually need to reference them, which prevents the type checker from discovering real errors on affected lines.

Part of the solution might be replacing these annotations, as we encounter them, with the [`@ignore`](https://jsdoc.app/tags-ignore) tag. The `@ignore` tag exists to remove something from documentation, and has no effect on type checking within our codebase.

In addition to hiding these members from documentation, we may also want to:

- (A) Strip them from the generated type definitions. This way applications built on CesiumJS (with type checking) will see type errors when trying to access internal members. I was surprised to see tsd-jsdoc already strips types annotated with `@ignore`, I thought it'd be a separate tag, but maybe that's helpful for our purposes.
- (B) Add [`@internal`](https://tsdoc.org/pages/tags/internal/) tags to these members. This is a TSDoc tag, not a JSDoc tag, and we'd need to [special case it in the build](https://github.com/CesiumGS/cesium/blob/b63a3a4cdd257aa04c471bb45b904a835b3b0fd3/Tools/jsdoc/cesiumTags.js#L63-L70). But since the type definitions are intended for TypeScript projects, using TSDoc tags should work as intended, as long as we can prevent it from breaking our tsd-jsdoc builds.
- (C) Maybe there's some way to have everything prefixed with `_` be hidden automatically?

Finally, as @javagl has mentioned [elsewhere](https://github.com/CesiumGS/cesium/pull/13201#pullrequestreview-3787683471), we could consider reducing the use of file-scoped functions and the quantity of internal-but-not-private members that this pattern requires. I don't feel strongly either way about the file-scoped functions pattern, but we'd have a fair number of `@private` tags left to deal with even without the pattern, so the earlier workarounds remain important.

Related:

- #4434
- #8331

Contributor guide

Open the contributing guide

Research direction

Start by reading Tools/jsdoc/cesiumTags.js, the tsd-jsdoc handling of @ignore, and the related issues #4434 and #8331. Compare the proposed @ignore, @internal, and underscore approaches, then define a documented build behavior that hides internal members from published documentation and produces the intended type-definition errors without masking internal type-checking errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
build-system, developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.