Do you want to keep working on this? Otherwise I'd like to close it to reduce the number of open PRs.

@gabritto This is related to the work you're doing on param completions, since it would reduce the complexity of the tags you'd have to emit.

@typescript-bot pack this

Heya @gabritto, I've started to run the tarball bundle task on this PR at 4b8a67f. You can monitor the build here.

Hey @gabritto, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/149208/artifacts?artifactName=tgz&fileId=8B2125470116A7BF9A7289C1BFDDA7736082CFF5910E684C95C227817F09245202&fileName=/typescript-5.1.0-insiders.20230313.tgz"
    }
}

and then running npm install.

There is also a playground for this build and an npm module you can use via "typescript": "npm:@typescript-deploys/[email protected]".;

Also addresses or even fixes #11859

@typescript-bot pack this

Heya @gabritto, I've started to run the tarball bundle task on this PR at 43cf71b. You can monitor the build here.

Hey @gabritto, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/150374/artifacts?artifactName=tgz&fileId=E5E88A5F8045188B82960270C715D0A78C138184C23753A31FD491D58E32D32202&fileName=/typescript-5.1.0-insiders.20230320.tgz"
    }
}

and then running npm install.

There is also a playground for this build and an npm module you can use via "typescript": "npm:@typescript-deploys/[email protected]".;

The error should be JS-only, but I thought that JSDoc errors only show in JS anyway. Better test that though.

@a-tarasyuk do you want to keep working on this?

@sandersn Yes., I need some clarification for one case that strikes me as a bit exceptional :).

(2) When checking a function call, we don't get the correct types from the @param annotations following the new logic.

In both cases, we have binding pattern parameters

/**
 * @param {{ a: string, b: string }} foo
 */
function f({ a, b }, { c, d }) { }

/**
 * @param {number} a
 */
function f({ a, b }) { }

How should we determine when TypeScript should strictly use the type from @param and when it should look up @param by the binding element name during the resolution of a parameter type?

TypeScript follows logic wherein, if there is a declared type (in current case jsdoc @param) for a parameter (as described in the lookup logic below), it uses that type. In both scenarios, it resolves the @param tag and uses the type from it.

const declaredType = tryGetTypeFromEffectiveTypeNode(declaration);
...
if (declaredType) {
    return addOptionality(declaredType, isProperty, isOptional);
}

1. TypeScript jsdoc resolver seeks to find a @param tag by its name
2. Following that, it attempts to find the @param by its index.

As far as I can tell, both calls match tags by index and not by name. The second examples fails because the top-level parameter { a, b } doesn't have a named tag (it doesn't have an identifier for a name anyway), so it falls back to index-based matching, and incorrectly grabs the type number for { a, b }. Is that what you were showing with your example?

I can see two fixes here:

1. Fancy fix: top-level parameters should skip matching by index if they are a binding pattern and some members of their pattern has a matching tag. This sounds complex and possibly slow.
2. Dumb fix: binding patterns shouldn't match by index. But this breaks existing code, I think.
3. Something else: tryGetTypeFromEffectiveTypeNode could pass down a parameter like isBindingPattern that could do the fancy check only when needed, or maybe the fancy check could instead be a recursive attempt to get the effective types of its properties and build an object type for the entire parameter.

For (1) and (2), though, I don't know whether call checking will then work, because @param {number} a only provides a type for the binding pattern property, not the entire binding pattern. This needs to be tested and fixed (somehow?) if it doesn't work.