Typedoc: The @internal doc flag recognised by tsc should be an alias for @hidden

[thombles]

The @internal flag is used by tsc --stripInternal to exclude a particular property from a generated declaration file. If you're producing a documented library with public methods for consumption this is basically the same as the @hidden flag you'll want to use in your typedoc.

It would be great if I could just use @internal and have it work on both my .d.ts and typedoc output.

I realise PRs are needed to make progress on typedoc at the moment but I thought I'd put this up as an issue in case anybody has any better ideas!

[aciccarello]

Great idea! Looks like these lines are where the @hidden tag is recognized.

Should the @internal docs only be ignored with the --stripInternal flag?

[aciccarello]

Should consider adding @ignore to the possible aliases. See #198

[christopherthielen]

I wrote a plugin for my project which allows me to mark specific code as @internal or @external.

https://github.com/christopherthielen/typedoc-plugin-internal-external

The plugin also allows you to specify aliases for each annotation.

https://github.com/christopherthielen/typedoc-plugin-internal-external#annotation-aliases

[aciccarello]

@christopherthielen I noticed your plugin just this week. The aliases look like a great opt-in way to workaround this so thanks for sharing. I think it would be great to have some documentation pointing people to 3rd party plugins like this.

I've been hesitant to merge #525 because @internal was designed by Microsoft with a slightly different use case. My understanding of the TypeScript feature is limited and I want to avoid aliasing it to a concept which may not be the same. Additionally, TypeScript has a --stripInternal flag which I think TypeDoc should respect. Users may have the @internal doc flag used in their code but the strip internal flag turned off. Or users may want simpler declaration files but a more complete documentation website.

Actions steps I think should be taken

• [ ] Symbols with @internal doc flag should be removed when the TypeScript --stripInternal flag is set
• [ ] Look into allowing themes tracking/setting the visibility of internal apis (based on the @internal flag)
• [ ] Review and document how external/internal code (as TypeDoc currently defines) is distinguished

[waterplea]

Does @internal still work? I don't see it on the compiler options page and when I use it in my Angular library and set stripInternal to true in tsconfig.json — marked properties still get to the final .d.ts file.

[Gerrit0]

TypeDoc doesn't produce declaration files, so I don't think it's a TypeDoc issue.

The TypeScript compiler options page doesn't list all options, nor does tsc --help. If you want to see all options (which does list --stripInternal) you have to run tsc --help --all