Support `@callback` nested parameter types for JSDoc

TypeScript Version: 3.7.x-dev.20200109

Search Terms: JSDoc callback nested parameter

Code Our SDK is written in Javascript, compiled with respect ES2015 and uses the following JSDoc construct with success to generate API reference. We make heavy use of user-supplied callbacks and we let users take advantage of Object destructuring in the parameter list.

I am trying to enable our Typescript consumers to leverage autocompletion and type-checking in conjunction with our SDK and make their lives easier.

/**
 * @callback WorksWithPeopleCallback
 * @param {Object} person
 * @param {String} person.name
 * @param {Number} [person.age]
 * @returns {void}
 */

/**
 * For each person, calls your callback.
 * @param {WorksWithPeopleCallback} callback
 * @returns {Promise<void>}
 */
function eachPerson(callback) {
}

Expected behavior:

declare function eachPerson(callback: WorksWithPeopleCallback): Promise<void>;
type WorksWithPeopleCallback = (person: { name: string, age?: number }) => void;

Actual behavior:

declare function eachPerson(callback: WorksWithPeopleCallback): Promise<void>;
type WorksWithPeopleCallback = (person: any, name: string, age?: number) => void;

In my opinion, this is a bug, though a subtle one.

Nested parameter types are ignored by a condition parser.ts (https://github.com/microsoft/TypeScript/blob/v3.7.4/src/compiler/parser.ts#L7041). I tried to recompile tsc after removing the condition and it seems to work fine.

Before I submit the PR, please explain if there is a reason for this feature being deliberately disabled.

Playground Link: https://www.typescriptlang.org/play/?module=1&useJavaScript=true#code/PQKhCgAIUgBBjAhgG2QI0fA1pA6gewCcsBnXASwBcALABQFN8AHZegYRXUyyhlicSFEAW0gBvAPJoAVvXiUAvpCb1CJfADtecAUNFiAypULkNAcyUq1mgHQaR9bf0EjxAOQCuwtKqUBtK3UNG0QzegBdJ0J6Sg9CDRJxADd8cgATBV5gcHBQCGhIADEiSHpMamVVIIAaSCRURIBPfDi6zgxsGyddVzECYjIqOkYWdnbuJXqubCiYuITxWkJ8YXISegAeFPSAPkzobIAzDw15ck1S8oZrDQAKKY6sAEpxcEygA

It works for sure in pure Typescript: https://www.typescriptlang.org/play/#code/C4TwDgpgBAwghgGwQIzgYwNZQLxQBSQBOAzgPYB2AXFAN5TlwC2E1xwhAluQOYA0UcbhAD81cgFdGyCISgBfAJQ4AfFABupDgBMA3ACg9AM3Hk0wDhShhCpNBGLE8aRCnQZq8JKkxKaeqAFQzl5ueHQMzNQARHBR8gr6ckA

[yin]

Most likely name and age params in example should be prefixed with person.

Sure, they should have been. I fixed that.

UPD. @typedef can help in the meantime if you haven’t tried yet.

I am aware of that. Until my PR get’s merged and released, I’ll have to leave callbacks out of the declarations to avoid people using those @typedef’s outside the callbacks.

Commit https://github.com/yin/TypeScript/commit/93de9cc04141b6d25e5aa0eb65a2cc96b089e1c3 is going into PR tomorrow.

EDIT: The test case in my commit has been updated too.

[yin]

I was debugging the issue for a few days, the problem seems to lie in the emitter and other code would need to be reworked. Too much work for me.