See the (sole) use of this function -- at x in @param obj.x we should return the symbol for x. Add a find-all-references test.

/**
 * @param obj.[|x|]
 */
function f(obj) {
    obj.[|x|];
}

Added.

This expression is too large.

const prop = node as JSDocPropertyLikeTag;
const flags = prop.isBracketed || prop.typeExpression && prop.typeExpression.type.kind === SyntaxKind.JSDocOptionalType
    ? SymbolFlags.Property | SymbolFlags.Optional
    : SymbolFlags.Property;
return declareSymbolAndAddToSymbolTable(prop, flags, SymbolFlags.PropertyExcludes);

Also, typeExpression is declared non-optional, but here we test for its presence.

Done

getDeclarationOfKind hides a loop, so this loops twice. Could add a version of that function that takes two kinds.

I'll just use findDeclaration which takes a predicate.

I was going to delete that function in #17380 since it's equivalent to just find(symbol.declarations, ...) -- this would be one of only 2 uses.

If this applies to more than just parameters, it should be renamed.

Done

Maybe this should wait for a separate PR, but I would much prefer to see code like:

const { isParameterNameFirst, fullName, typeExpression } = node as JSDocPropertyLikeTag;

in all of these cases, instead of repeated casting.

I will make the change here if you are willing to review it! 😅 I'll put it in a separate commit at the end which might make it easier.

Please make a separate PR as that would be a huge diff.

It looks like name is a pointer to a node within fullName. So it would be visited twice if we were recursively calling forEachChild.

Nice catch! I added fullName later and didn't notice that name needed to be removed.

Fixed

Since target is now an enum, use an explicit comparison instead of treating it like a boolean.

Done

Use a switch.

Done

isTypeReferenceNode just tests the syntax kind, so just make that a switch case and have default: return false;.

It no longer makes sense to have separate preName and postName variables. Just create isParameterNameFirst directly.

Done

Since there are only 2 possible targets, maybe there should just be 2 different functions parseChildParmeterTag and parseChildPropertyTag that both use parseChildParameterOrPropertyTagCommon?

I think a more likely refactoring would be to pass 1 of 2 different tryParseChildTag functions instead of the target enum. But the target enum pattern is also used with parseParameterOrPropertyTag, and it's as easy to read and (probably?) as fast to run, so I think I'll keep it this way.

You could just the create the mutable array locally and assign to jsdocTypeLiteralat the end. That way you avoid casting an already-created object to mutable.
This loop could probably be its own function parseParameterTags returning NodeArray<JSDocPropertyTag> | undefined.
Also, you don't appear to be setting the position on the array -- if you don't want to do that, just declare it as an ReadonlyArray and not a NodeArray.
Also, what's with the cast on child? You passed in PropertyLikeParse.Parameter so it's surprising to see an assertion that what you got back isn't a parameter.

I don't know a correct position to set on the child array because I don't know what would use it. I don't think I can make it a ReadonlyArray though, because forEachChild expects to iterate over a NodeArray. For now I'll still create a NodeArray with no position.

You could just use a for loop instead of calling cbNodes, which does require a NodeArray, meaning users might be expecting it to have a position.

Sure. Done.

Isn't this redundant? Why do we have both typeExpression and type?

I wasn't sure how much like a real VariableDeclaration JSDocPropertyLikeTag should become and ended up halfway there. It turns out to be easier to continue special-casing it in getTypeOfVariableOrParameterOrProperty instead of having it become a full-fledged declaration. I dropped type in favour of typeExpression.

This is also redundant, I would just make this a function of the node and not a property.

This was another convenience shim. I turned name into fullName and pushed the isIdentifier check into getNameOfDeclaration.

Nit: line before a closing bracket doesn't really accomplish anything -- nothing to separate that isn't already separated by the closing bracket.

What happens to child in this case? We just drop it with no syntax error?

I think this comment is still unaddressed?

Yes. It happens in this case:

/**
 * @typedef Name
 * @type {string}
 * @type {Oops} - this is dropped and we stop parsing the @typedef
 */

This would be a grammar error if we did more thorough checking of jsdoc structure in the checker (along with a lot of other incorrect-but-allowed jsdoc). We don't, which is OK relative to what we used to provide. We should probably improve in the future if jsdoc becomes the source of types for significant, typed codebases.

OK, added #17442.

See earlier comment on casting to MutableNodeArray.

What are our performance guidelines on optionally vs unconditionally assigning to a property?

I thought the standard for booleans was to declare them as b?: boolean and only assign them when needed. What difference in performance could arise? Conditional assignment saves space (but how much I don't know) versus unconditional assignment, which could be better for [de]optimisation. @rbuckton do you have an opinion?

Nit: would just name these variables a and b since they don't really depend on a parent-child context.

Done.

Nit: indent switch body

Fixed

Should this be break loop? It looks like the way it is currently, it goes all the way to the end of the file, when we could stop the moment we see something that isn't an @param tag with the correct name.

This function is always called from in a speculative context, so I can actually just return false.

Do we have an established pattern for re-setting the scanner? What if scanner has some other state that this doesn't reset?

Yep, this is left over from the old scanChildTags that faked its own speculative parsing. Removed.

This is only called in one place, and alreadyHasTypeTag is never provided.

Oops, I moved that up a couple of levels and forgot to remove it here.

Is the information about what tag name was used available in the AST? That might be useful for linting.

Yes, JSDocTag.tagName: Identifier, so it looks like it's preserved on all JSDocTags.

A more useful lint rule would be to look for mismatched typedef/param and param/property nestings, since the compiler currently ignores them:

/**
 * @typedef {object} x
 * @param {string} x.a - WRONG! (but ignored by the compiler)
 *
 * @param {object} y
 * @property {string} y.a - WRONG! (but ignored by the compiler)
 */

This is only called in one place, and createIfMissing is always true.

This could use:

function createQualifiedName(entity: EntityName, name: Identifier): QualifiedName {
    const node = createNode(SyntaxKind.QualifiedName, entity.pos) as QualifiedName;
    node.left = entity;
    node.right = name;
    return finishNode(node);
}

And you can re-use createQualifiedName in parseEntityName. (parseJSDocEntityName should probably be near parseEntityName since they are similar.)

Done. I thought about merging parseEntityName and parseJSDocEntityName, but they both worry about ad-hoc jsdoc-related things, plus they call into different identifier parsers which do the same.

These two if blocks are the same, so use this helper:

function pushName(name: Identifier) {
    pushCommentRange(pos, name.pos - pos);
    pushClassification(name.pos, name.end - name.pos, ClassificationType.parameterName);
    pos = name.end;
}

Don't know why this shows as outdated, it still seems relevant.

I think we should bail out immediately if it's not an identifier, instead of continuing with an undefined nameThusFar.

Done. I returned emptyArray instead of undefined. I'm not sure whether that's correct.

Should be fine.