[api-extractor] Allow separate release tags for overloaded functions and methods

[D4N14L]

(PR description added by @octogonz since it was missing)

I assume this PR is related to #972 (comment):

@johnguy0 asked today about support for function overloads as a special case. For example:

/** @beta */
export function add(x: string, y: string): string;

/** @public */
export function add(x: number, y: number): number;

// implementation
export function add(x: string|number, y: string|number): string|number {
}

This seems relatively safe.

[octogonz]

@D4N14L the TSDoc tags such as @public and @internal are called "release tags". Whereas "accessibility modifiers" is used for the TypeScript keywords such as public and protected.

[octogonz]

@D4N14L Thanks for implementing this BTW! It's a pretty useful feature and we've had many requests for it.

[octogonz]

Is this check still needed? It seems redundant since we're checking each individual declaration below.

[D4N14L]

I thought about this when adding... I figured keeping the old behaviour was alright (rolls up the comments to one symbol when they're all excluded) however, it makes more sense to have it consistent. I'll make the change

[octogonz]

Overall this PR looks fine, however there were a couple places where the logic was a little difficult to follow, or did not consider possible configurations where the validation rules are suppressed.

Here's a PR with a proposed simplification: D4N14L#1

I'll add some comments to that PR explaining the issues.

[octogonz]

Looks good. If you don't have any further changes or validations you'd like to do, then I'm good with merging. Thanks again for implementing this!

[D4N14L]

Looks good. If you don't have any further changes or validations you'd like to do, then I'm good with merging. Thanks again for implementing this!

@octogonz I was still going to look at removing that duplicate check above, however I'm noticing that it actually breaks the build on api-extractor-test-04 (it tries to export Lib1Interface even though it's only available in @Alpha. If you'd like to take a look at this feel free, but if not I was going to look into it on Monday

[octogonz]

I was still going to look at removing that duplicate check above, however I'm noticing that it actually breaks the build on api-extractor-test-04 (it tries to export Lib1Interface even though it's only available in @Alpha. If you'd like to take a look at this feel free, but if not I was going to look into it on Monday

@D4N14L The reason is that the continue; also prevents the DtsEmitHelpers.emitNamedExport() step from happening later in that loop.

So this your existing implementation seems like the correct behavior to me: If all declarations are trimmed, then we shouldn't export the symbol, and we can put one consolidated comment. Whereas if at least one declaration is untrimmed, then we need to export the symbol, and should put individual comments.

To make this distinction more explicit, I'm going to change the text of the emitted comment slightly for the second case. But otherwise I think we're good to merge this PR. 👍

[octogonz]

This feature was published with API Extractor 7.5.0