Using @internal on @Prop()s to exclude from doc generation can cause build errors

[trazek]

Stencil version:

 @stencil/core@1.12.7

I'm submitting a:

[ ] bug report
[x ] feature request
[ ] support request => Please do not submit support requests here, use one of these channels: https://stencil-worldwide.herokuapp.com/ or https://forum.ionicframework.com/

Current behavior:

Tagging @internal on @Prop() variables could cause build errors since it removes the types from TypeScript compilation.

Expected behavior:

Exclude @Prop() variables from doc generation without causing build errors

Steps to reproduce:

Add @internal to @Prop() variables used by other components in a library will cause like this:

[ ERROR ]  TypeScript: ./src/components/list-line/list-line.tsx:112:15
           Type '{ key: number; checkChanges: boolean; lines: string; innerHTML: any; }' is not assignable to type
           'UsgLineTruncation & HTMLAttributes<HTMLUsgLineTruncationElement>'.Property 'checkChanges' does not exist on
           type 'UsgLineTruncation & HTMLAttributes<HTMLUsgLineTruncationElement>'.

    L111:  key={Date.now()}
    L112:  checkChanges={false}
    L113:  lines={this.lines}

In the above example list-line uses list-line-truncation directly and the build fails since checkChanges is tagged @internal to avoid docs generation

Other information:

[manucorporat]

We want to encourage public APIS to have docs, what's the use case for non wanting the api documented but still exposed?

[trazek]

When creating a component library that has components with interact and use other components internally, we don't always want consumers interacting with certain props and events. Especially if those props and events are used only internally. So this provides an easy and benign way for library authors to exclude things from the docs generation without disturbing the build. I noticed another person asked about this as well -- #1849 The suggestion to use the @internal works if the component is not used by another but has build issues if it is

[trazek]

Does this sound reasonable @manucorporat ?