rushstack
rushstack copied to clipboard
[api-extractor] Fallback to first overload on missing selector
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.