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

[donmccurdy]

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 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 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 tags to these members. This is a TSDoc tag, not a JSDoc tag, and we'd need to special case it in the build. 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, 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:

• Let us slowly move to Typescript. (instructions inside) #4434
• RenderState is private but is an option in a public class #8331

[jjspace]

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.

As far as I understand the system (and hopefully remember correctly) tsd-jsdoc parses everything with JSDoc first then generates a types file from the generated doc structure. If JSDoc doesn't know about a property or function then the types file won't have it either. This would probably be one of the benefits of other efforts we've discussed around replacing tsd-jsdoc with tsc directly.
(I think this is actually why #13203 has no properties in the generated type)

I will also crosslink to my previous comments directly on this aspect around @private being too restrictive imo. #4434 (comment)