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.

Inizia analizzando la gestione dei flag del compilatore TypeScript e il comportamento dell’emissione delle dichiarazioni, in particolare il modo in cui --stripInternal filtra attualmente le dichiarazioni. Definisci test per --onlyExternal, incluse annotazioni @external e @internal annidate, prima di implementare la semantica di filtraggio richiesta. Il lavoro è completato quando l’output delle dichiarazioni contiene solo gli elementi annotati esternamente consentiti e i relativi percorsi padre, secondo le regole di annidamento indicate.