[api-extractor] Fix an issue where destructured parameters were handled incorrectly

[octogonz]

Summary

Consider these functions:

export function printReport(title: string, {verbose}: {verbose:boolean}): void { 
  . . .
}

export function clearRange([min, max]: [min: number, max: number]): void { 
  . . .
}

API Extractor will incorrectly report the function parameter name as {verbose} or [min, max] which can sometimes cause an actual validation error when API Documenter was expecting a normal identifier.

Details

Discussed in this Zulip thread:

Comments in destructured parameters trigger errors

In a nutshell, the {verbose} string is:

• a local variable (implementation detail) that does not affect the public signature in any way that API consumers can detect
• awkward to handle in the docsite, which wants to present parameters as named objects
• problematic for other contexts like @param
• yet too ubiquitous to treat as an actual error, and probably required for some arcane type algebra scenarios

My proposed solution is to rewrite the signatures, synthesizing a conventional name for the anonymous parameter:

export function printReport(title: string, options: {verbose:boolean}): void { 
  . . .
}

export function clearRange(list: [min: number, max: number]): void { 
  . . .
}

The options and list names are used when there is exactly one destructured parameter. In more general cases (e.g. multiple such parameters), the naming pattern anonmyous, anonymous2, ... is used instead.

How it was tested

Impacted documentation

[octogonz]

Before merging, we can fix the ApiReportGenerator and DtsRollupGenerator as well. They are easier than ApiModelGenerator.

[ilg-ul]

The synthesised name options is probably right when added to optional parameters at the end of the list.

When there is a single set of destructured parameters, perhaps a more appropriate name would be params, instead of options.

[ilg-ul]

Does this patch also fixes the bug related to comments attached to destructured parameters?

[octogonz]

Does this patch also fixes the bug related to comments attached to destructured parameters?

Yes, if you look at the unit test, all comments get stripped during .d.ts emit except for one (// slash P3), which is in the subexpression that we are transforming.