feat: internal accessibility

[eladb]

Respect the @internal jsdoc tag on types and members. Any type of member marked internal will not be exposed in the API of the module and in .d.ts. files (through --strip-internal).

Members (properties/methods) that are marked as @internal must also have an underscore prefix (i.e. _myMethod) and vice versa in order to ensure that implementers or subclasses won't modify accessibility.

If a class implements (or an interface extends) an internal or private interface, that interface is erased from the implementer's API. So it is possible to use internal interfaces as bases, while still maintaining API integrity (related to #287).

Fixes #388

BREAKING CHANGE: member names that begin with underscore now must be marked as "@internal" in their jsdocs, which will cause them to disappear from type declaration files and jsii APIs.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[RomainMuller]

Other question that occurred to me now... is @internal on a method inherited by overrides or not? If not, the case for making a single method on an interface internal is really awkward, since that'd have to be repeated for every single implementation of it...

[eladb]

Other question that occurred to me now... is @internal on a method inherited by overrides or not? If not, the case for making a single method on an interface internal is really awkward, since that'd have to be repeated for every single implementation of it...

That's a good question. Let me check

[eladb]

So the answer is that you have to explicitly define @internal on all inherited members, or otherwise the typescript compiler will make the method visible. Does it make sense to enforce this with jsii? I guess it does, no?

[RomainMuller]

The doc does no longer reflect what the implementation does.