Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: internal accessibility #390

Merged
merged 4 commits into from
Mar 19, 2019
Merged

feat: internal accessibility #390

merged 4 commits into from
Mar 19, 2019

Conversation

eladb
Copy link
Contributor

@eladb eladb commented Mar 18, 2019

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.

strips classes, interfaces, enums or members that have an "@internal"
jsdoc tag both from the jsii assembly manifest and .d.ts

fixes #388
@eladb eladb requested a review from a team as a code owner March 18, 2019 22:58
@RomainMuller
Copy link
Contributor

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
Copy link
Contributor Author

eladb commented Mar 19, 2019

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
Copy link
Contributor Author

eladb commented Mar 19, 2019

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?

@eladb eladb changed the title feat: strip @internal feat: internal Mar 19, 2019
@eladb eladb changed the title feat: internal feat: internal accessibility Mar 19, 2019
@eladb eladb merged commit e232cb5 into master Mar 19, 2019
@eladb eladb deleted the benisrae/strip-internal branch March 19, 2019 13:03
@@ -1051,17 +1128,34 @@ function _isExported(node: ts.Declaration): boolean {
}

/**
* Members with names starting with ``_`` and members that are private are hidden.
* Members with names starting with `_` (and marked as @internal) and members
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The doc does no longer reflect what the implementation does.

packages/jsii/lib/assembler.ts Show resolved Hide resolved
packages/jsii/lib/assembler.ts Show resolved Hide resolved
packages/jsii/lib/assembler.ts Show resolved Hide resolved
packages/jsii/lib/assembler.ts Show resolved Hide resolved
packages/jsii/lib/assembler.ts Show resolved Hide resolved
packages/jsii/lib/assembler.ts Show resolved Hide resolved
eladb pushed a commit that referenced this pull request Mar 19, 2019
When a type inherits (extends/implements) from a hidden (private/internal)
interface, and that interface extends a non-hidden interface, we need to 
copy the non-hidden interface to the consuming type so that it can be polymorphically
used.

Follow up on #390

Co-authored-by: RomainMuller <[email protected]>
eladb pushed a commit that referenced this pull request Mar 19, 2019
When a type inherits (extends/implements) from a hidden (private/internal)
interface, and that interface extends a non-hidden interface, we need to 
copy the non-hidden interface to the consuming type so that it can be polymorphically
used.

Follow up on #390

Co-authored-by: RomainMuller <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

strip elements marked with @internal jsdoc tag
3 participants