Only emit declarations for code that has an /** @external */ JSDoc annotation

Search Terms

external emit declaration

Problem

When working with the --stripInternal compiler flag, you want to create a clean declaration file that only exposes the stuff your library users should use.
You as library developer must add the /* @internal */ annotations to all the parts of your code you don't want in the declaration file. 'Sloppy developers in the team' forget to set this annotation and expose stuff without realizing it.

Suggestion

It would be handy if we could reverse this.
We could start with an empty declaration file when a compiler flag --onlyExternal is set and only expose the things that have an /* @external */ JSDoc annotation

• /* @external */ exposes the 'item' and the 'parent path' to acces it.
• /* @internal */ used inside an /* @external */ parent hides the 'item' and and all its children.
• /* @external */ used inside an /* @internal */ parent is ignored and stays internal.

Remarks

• When using the /* @internal */ annotation, you mostly try to place it on top level structures (like namespaces). In these cases it is not a problem when code is added to the namespace. It is mostly a problem when new files or namespaces are added.
• When using the suggested /* @external */ annotation, you normally will place it more deeply, like on specific functions, variables or classes to expose.

Start by investigating TypeScript's compiler flag handling and declaration emit behavior, especially how --stripInternal currently filters declarations. Define tests for --onlyExternal, including nested @external and @internal annotations, before implementing the requested filtering semantics. Done means declaration output contains only permitted externally annotated items and their parent paths, with the stated nesting rules.