rushstack icon indicating copy to clipboard operation
rushstack copied to clipboard

[api-extractor] Fallback to first overload on missing selector

Open daymxn opened this issue 1 year ago • 0 comments

Summary

When a @link is ambiguous due to multiple declarations, it's currently just removed from the generated documentation- creating invalid docs.

Instead, it would be nice if api-extractor continued to output a warning, but in the generated output it fell back to the first definition (which is how typescript does it currently, at least per VSCode intellisense).

Details

VSCode intellisense does not properly support TSDoc member reference selectors. But, if you exclude a selector, api-extractor gives a ae-unresolved-link warning, and the generated output excludes the broken link.

This means that a developer (currently) needs to choose between having broken VSCode intellisense or broken TSDoc generated docs.

(ae-unresolved-link) The @link reference could not be resolved: 
The reference is ambiguous because "instanceOf" has more than one declaration; 
you need to add a TSDoc member reference selector

VSCode intellisense links to the first definition, and it would be helpful if api-extractor did the same (when selectors are not present).

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question Answer
@microsoft/api-extractor version? 7.47.9
Operating system? Windows/Linux/Mac
API Extractor scenario? docs (.api.json)
Would you consider contributing a PR? Yes[^1]
TypeScript compiler version? 5.5.3
Node.js version (node -v)? N/A

[^1]: The api-extractor infrastructure is honestly pretty confusing. I've tried setting it up to make a PR for a related feature, but it was fairly convoluted and difficult.

daymxn avatar Oct 13 '24 16:10 daymxn